Clarify showDuration and waitDuration API docs and test behavior (#36970)

* Improve showDuration and waitDuration explanation and tests

* Add condition to test to ensure that tooltip does not show before long press duration is over

packages/flutter/lib/src/material/tooltip.dart

@@ -124,10 +124,14 @@ class Tooltip extends StatefulWidget {
   /// The length of time that a pointer must hover over a tooltip's widget
   /// before the tooltip will be shown.
   ///
+  /// Once the pointer leaves the widget, the tooltip will immediately
+  /// disappear.
+  ///
   /// Defaults to 0 milliseconds (tooltips are shown immediately upon hover).
   final Duration waitDuration;
 
-  /// The length of time that the tooltip will be shown once it has appeared.
+  /// The length of time that the tooltip will be shown after a long press
+  /// is released.
   ///
   /// Defaults to 1.5 seconds.
   final Duration showDuration;
@@ -220,7 +224,7 @@ class _TooltipState extends State<Tooltip> with SingleTickerProviderStateMixin {
       return;
     }
     if (_longPressActivated) {
-      // Tool tips activated by long press should stay around for 1.5s.
+      // Tool tips activated by long press should stay around for the showDuration.
       _hideTimer ??= Timer(showDuration, _controller.reverse);
     } else {
       // Tool tips activated by hover should disappear as soon as the mouse

packages/flutter/test/material/tooltip_test.dart

@@ -574,7 +574,7 @@ void main() {
     ));
   }, skip: isBrowser);
 
-  testWidgets('Tooltip stays around', (WidgetTester tester) async {
+  testWidgets('Tooltip stays after long press', (WidgetTester tester) async {
     await tester.pumpWidget(
       MaterialApp(
         home: Center(
@@ -592,18 +592,30 @@ void main() {
 
     final Finder tooltip = find.byType(Tooltip);
     TestGesture gesture = await tester.startGesture(tester.getCenter(tooltip));
+
+    // long press reveals tooltip
     await tester.pump(kLongPressTimeout);
     await tester.pump(const Duration(milliseconds: 10));
-    await gesture.up();
     expect(find.text(tooltipText), findsOneWidget);
+    await gesture.up();
+
+    // tap (down, up) gesture hides tooltip, since its not
+    // a long press
     await tester.tap(tooltip);
     await tester.pump(const Duration(milliseconds: 10));
+    expect(find.text(tooltipText), findsNothing);
+
+    // long press once more
     gesture = await tester.startGesture(tester.getCenter(tooltip));
     await tester.pump();
     await tester.pump(const Duration(milliseconds: 300));
     expect(find.text(tooltipText), findsNothing);
+
     await tester.pump(kLongPressTimeout);
+    await tester.pump(const Duration(milliseconds: 10));
     expect(find.text(tooltipText), findsOneWidget);
+
+    // keep holding the long press, should still show tooltip
     await tester.pump(kLongPressTimeout);
     expect(find.text(tooltipText), findsOneWidget);
     gesture.up();
@@ -611,7 +623,6 @@ void main() {
 
   testWidgets('Tooltip shows/hides when hovered', (WidgetTester tester) async {
     const Duration waitDuration = Duration(milliseconds: 0);
-    const Duration showDuration = Duration(milliseconds: 1500);
     final TestGesture gesture = await tester.createGesture(kind: PointerDeviceKind.mouse);
     await gesture.addPointer();
     await gesture.moveTo(const Offset(1.0, 1.0));
@@ -623,7 +634,6 @@ void main() {
         home: Center(
           child: Tooltip(
             message: tooltipText,
-            showDuration: showDuration,
             waitDuration: waitDuration,
             child: Container(
               width: 100.0,
@@ -653,7 +663,6 @@ void main() {
     await tester.pump();
 
     // Wait for it to disappear.
-    await tester.pump(showDuration);
     await tester.pumpAndSettle();
     await gesture.removePointer();
     expect(find.text(tooltipText), findsNothing);