diff --git a/lib/ui/semantics.dart b/lib/ui/semantics.dart
index e73f8335251f7..bee542328c055 100644
--- a/lib/ui/semantics.dart
+++ b/lib/ui/semantics.dart
@@ -8,10 +8,12 @@ part of dart.ui;
 
 /// The possible actions that can be conveyed from the operating system
 /// accessibility APIs to a semantics node.
-//
-// When changes are made to this class, the equivalent APIs in
-// `lib/ui/semantics/semantics_node.h` and in each of the embedders *must* be
-// updated.
+///
+/// \warning When changes are made to this class, the equivalent APIs in
+///         `lib/ui/semantics/semantics_node.h` and in each of the embedders
+///         *must* be updated.
+/// See also:
+///   - file://./../../lib/ui/semantics/semantics_node.h
 class SemanticsAction {
   const SemanticsAction._(this.index) : assert(index != null); // ignore: unnecessary_null_comparison
 
diff --git a/lib/ui/semantics/semantics_node.h b/lib/ui/semantics/semantics_node.h
index 97543f00def94..cc98c8656a867 100644
--- a/lib/ui/semantics/semantics_node.h
+++ b/lib/ui/semantics/semantics_node.h
@@ -48,7 +48,12 @@ const int kScrollableSemanticsActions =
     static_cast<int32_t>(SemanticsAction::kScrollUp) |
     static_cast<int32_t>(SemanticsAction::kScrollDown);
 
-// Must match the SemanticsFlags enum in semantics.dart.
+/// C/C++ representation of `SemanticsFlags` defined in
+/// `lib/ui/semantics.dart`.
+///\warning This must match the `SemanticsFlags` enum in
+///         `lib/ui/semantics.dart`.
+/// See also:
+///   - file://./../../../lib/ui/semantics.dart
 enum class SemanticsFlags : int32_t {
   kHasCheckedState = 1 << 0,
   kIsChecked = 1 << 1,