Added a more complete docstring for SemanticsFlags (flutter#19817)

Author: gaaclarke

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
 

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,