Clarifies semantics long press and semantics on tap documentation (#1…

…28599)

fixes flutter/flutter#35112

packages/flutter/lib/src/semantics/semantics.dart

@@ -1367,18 +1367,29 @@ class SemanticsProperties extends DiagnosticableTree {
   /// the finger without moving it. For example, a button should implement this
   /// action.
   ///
-  /// VoiceOver users on iOS and TalkBack users on Android can trigger this
+  /// VoiceOver users on iOS and TalkBack users on Android *may* trigger this
   /// action by double-tapping the screen while an element is focused.
+  ///
+  /// Note: different OSes or assistive technologies may decide to interpret
+  /// user inputs differently. Some may simulate real screen taps, while others
+  /// may call semantics tap. One way to handle taps properly is to provide the
+  /// same handler to both gesture tap and semantics tap.
   final VoidCallback? onTap;
 
   /// The handler for [SemanticsAction.longPress].
   ///
   /// This is the semantic equivalent of a user pressing and holding the screen
   /// with the finger for a few seconds without moving it.
   ///
-  /// VoiceOver users on iOS and TalkBack users on Android can trigger this
+  /// VoiceOver users on iOS and TalkBack users on Android *may* trigger this
   /// action by double-tapping the screen without lifting the finger after the
   /// second tap.
+  ///
+  /// Note: different OSes or assistive technologies may decide to interpret
+  /// user inputs differently. Some may simulate real long presses, while others
+  /// may call semantics long press. One way to handle long press properly is to
+  /// provide the same handler to both gesture long press and semantics long
+  /// press.
   final VoidCallback? onLongPress;
 
   /// The handler for [SemanticsAction.scrollLeft].

packages/flutter/lib/src/widgets/basic.dart

@@ -6983,6 +6983,8 @@ class MetaData extends SingleChildRenderObjectWidget {
 ///
 /// See also:
 ///
+///  * [SemanticsProperties], which contains a complete documentation for each
+///    of the constructor parameters that belongs to semantics properties.
 ///  * [MergeSemantics], which marks a subtree as being a single node for
 ///    accessibility purposes.
 ///  * [ExcludeSemantics], which excludes a subtree from the semantics tree
@@ -7004,6 +7006,8 @@ class Semantics extends SingleChildRenderObjectWidget {
   ///
   /// See also:
   ///
+  ///  * [SemanticsProperties], which contains a complete documentation for each
+  ///    of the constructor parameters that belongs to semantics properties.
   ///  * [SemanticsSortKey] for a class that determines accessibility traversal
   ///    order.
   Semantics({