Normalizes all of the "See also" blocks in comments. (#46121)

This normalizes all of the "See also" blocks in comments so that they conform in style.

They all look like this now:

  /// See also:
  ///
  ///  * [MyFavoriteWidget], because it's cool.
  class Foo {}

I removed some useless "See also" blocks, and added commentary to ones that were just "bare" references.

This is my penance for adding so many bullets that are "-" instead of "*". :-)

packages/flutter/lib/src/cupertino/colors.dart

@@ -98,8 +98,8 @@ class CupertinoColors {
   ///
   /// See also:
   ///
-  /// * [UIColor.systemBlue](https://developer.apple.com/documentation/uikit/uicolor/3173141-systemblue),
-  ///   the `UIKit` equivalent.
+  ///  * [UIColor.systemBlue](https://developer.apple.com/documentation/uikit/uicolor/3173141-systemblue),
+  ///    the `UIKit` equivalent.
   static const CupertinoDynamicColor systemBlue = CupertinoDynamicColor.withBrightnessAndContrast(
     debugLabel: 'systemBlue',
     color: Color.fromARGB(255, 0, 122, 255),
@@ -112,8 +112,8 @@ class CupertinoColors {
   ///
   /// See also:
   ///
-  /// * [UIColor.systemGreen](https://developer.apple.com/documentation/uikit/uicolor/3173144-systemgreen),
-  ///   the `UIKit` equivalent.
+  ///  * [UIColor.systemGreen](https://developer.apple.com/documentation/uikit/uicolor/3173144-systemgreen),
+  ///    the `UIKit` equivalent.
   static const CupertinoDynamicColor systemGreen = CupertinoDynamicColor.withBrightnessAndContrast(
     debugLabel: 'systemGreen',
     color: Color.fromARGB(255, 52, 199, 89),
@@ -126,8 +126,8 @@ class CupertinoColors {
   ///
   /// See also:
   ///
-  /// * [UIColor.systemIndigo](https://developer.apple.com/documentation/uikit/uicolor/3173146-systemindigo),
-  ///   the `UIKit` equivalent.
+  ///  * [UIColor.systemIndigo](https://developer.apple.com/documentation/uikit/uicolor/3173146-systemindigo),
+  ///    the `UIKit` equivalent.
   static const CupertinoDynamicColor systemIndigo = CupertinoDynamicColor.withBrightnessAndContrast(
     debugLabel: 'systemIndigo',
     color: Color.fromARGB(255, 88, 86, 214),
@@ -140,8 +140,8 @@ class CupertinoColors {
   ///
   /// See also:
   ///
-  /// * [UIColor.systemOrange](https://developer.apple.com/documentation/uikit/uicolor/3173147-systemorange),
-  ///   the `UIKit` equivalent.
+  ///  * [UIColor.systemOrange](https://developer.apple.com/documentation/uikit/uicolor/3173147-systemorange),
+  ///    the `UIKit` equivalent.
   static const CupertinoDynamicColor systemOrange = CupertinoDynamicColor.withBrightnessAndContrast(
     debugLabel: 'systemOrange',
     color: Color.fromARGB(255, 255, 149, 0),
@@ -154,8 +154,8 @@ class CupertinoColors {
   ///
   /// See also:
   ///
-  /// * [UIColor.systemPink](https://developer.apple.com/documentation/uikit/uicolor/3173148-systempink),
-  ///   the `UIKit` equivalent.
+  ///  * [UIColor.systemPink](https://developer.apple.com/documentation/uikit/uicolor/3173148-systempink),
+  ///    the `UIKit` equivalent.
   static const CupertinoDynamicColor systemPink = CupertinoDynamicColor.withBrightnessAndContrast(
     debugLabel: 'systemPink',
     color: Color.fromARGB(255, 255, 45, 85),
@@ -168,8 +168,8 @@ class CupertinoColors {
   ///
   /// See also:
   ///
-  /// * [UIColor.systemPurple](https://developer.apple.com/documentation/uikit/uicolor/3173149-systempurple),
-  ///   the `UIKit` equivalent.
+  ///  * [UIColor.systemPurple](https://developer.apple.com/documentation/uikit/uicolor/3173149-systempurple),
+  ///    the `UIKit` equivalent.
   static const CupertinoDynamicColor systemPurple = CupertinoDynamicColor.withBrightnessAndContrast(
     debugLabel: 'systemPurple',
     color: Color.fromARGB(255, 175, 82, 222),
@@ -182,8 +182,8 @@ class CupertinoColors {
   ///
   /// See also:
   ///
-  /// * [UIColor.systemRed](https://developer.apple.com/documentation/uikit/uicolor/3173150-systemred),
-  ///   the `UIKit` equivalent.
+  ///  * [UIColor.systemRed](https://developer.apple.com/documentation/uikit/uicolor/3173150-systemred),
+  ///    the `UIKit` equivalent.
   static const CupertinoDynamicColor systemRed = CupertinoDynamicColor.withBrightnessAndContrast(
     debugLabel: 'systemRed',
     color: Color.fromARGB(255, 255, 59, 48),
@@ -196,8 +196,8 @@ class CupertinoColors {
   ///
   /// See also:
   ///
-  /// * [UIColor.systemTeal](https://developer.apple.com/documentation/uikit/uicolor/3173151-systemteal),
-  ///   the `UIKit` equivalent.
+  ///  * [UIColor.systemTeal](https://developer.apple.com/documentation/uikit/uicolor/3173151-systemteal),
+  ///    the `UIKit` equivalent.
   static const CupertinoDynamicColor systemTeal = CupertinoDynamicColor.withBrightnessAndContrast(
     debugLabel: 'systemTeal',
     color: Color.fromARGB(255, 90, 200, 250),
@@ -210,8 +210,8 @@ class CupertinoColors {
   ///
   /// See also:
   ///
-  /// * [UIColor.systemYellow](https://developer.apple.com/documentation/uikit/uicolor/3173152-systemyellow),
-  ///   the `UIKit` equivalent.
+  ///  * [UIColor.systemYellow](https://developer.apple.com/documentation/uikit/uicolor/3173152-systemyellow),
+  ///    the `UIKit` equivalent.
   static const CupertinoDynamicColor systemYellow = CupertinoDynamicColor.withBrightnessAndContrast(
     debugLabel: 'systemYellow',
     color: Color.fromARGB(255, 255, 204, 0),
@@ -224,8 +224,8 @@ class CupertinoColors {
   ///
   /// See also:
   ///
-  /// * [UIColor.systemGray](https://developer.apple.com/documentation/uikit/uicolor/3173143-systemgray),
-  ///   the `UIKit` equivalent.
+  ///  * [UIColor.systemGray](https://developer.apple.com/documentation/uikit/uicolor/3173143-systemgray),
+  ///    the `UIKit` equivalent.
   static const CupertinoDynamicColor systemGrey = CupertinoDynamicColor.withBrightnessAndContrast(
     debugLabel: 'systemGrey',
     color: Color.fromARGB(255, 142, 142, 147),
@@ -238,8 +238,8 @@ class CupertinoColors {
   ///
   /// See also:
   ///
-  /// * [UIColor.systemGray2](https://developer.apple.com/documentation/uikit/uicolor/3255071-systemgray2),
-  ///   the `UIKit` equivalent.
+  ///  * [UIColor.systemGray2](https://developer.apple.com/documentation/uikit/uicolor/3255071-systemgray2),
+  ///    the `UIKit` equivalent.
   static const CupertinoDynamicColor systemGrey2 = CupertinoDynamicColor.withBrightnessAndContrast(
     debugLabel: 'systemGrey2',
     color: Color.fromARGB(255, 174, 174, 178),
@@ -252,8 +252,8 @@ class CupertinoColors {
   ///
   /// See also:
   ///
-  /// * [UIColor.systemGray3](https://developer.apple.com/documentation/uikit/uicolor/3255072-systemgray3),
-  ///   the `UIKit` equivalent.
+  ///  * [UIColor.systemGray3](https://developer.apple.com/documentation/uikit/uicolor/3255072-systemgray3),
+  ///    the `UIKit` equivalent.
   static const CupertinoDynamicColor systemGrey3 = CupertinoDynamicColor.withBrightnessAndContrast(
     debugLabel: 'systemGrey3',
     color: Color.fromARGB(255, 199, 199, 204),
@@ -266,8 +266,8 @@ class CupertinoColors {
   ///
   /// See also:
   ///
-  /// * [UIColor.systemGray4](https://developer.apple.com/documentation/uikit/uicolor/3255073-systemgray4),
-  ///   the `UIKit` equivalent.
+  ///  * [UIColor.systemGray4](https://developer.apple.com/documentation/uikit/uicolor/3255073-systemgray4),
+  ///    the `UIKit` equivalent.
   static const CupertinoDynamicColor systemGrey4 = CupertinoDynamicColor.withBrightnessAndContrast(
     debugLabel: 'systemGrey4',
     color: Color.fromARGB(255, 209, 209, 214),
@@ -280,8 +280,8 @@ class CupertinoColors {
   ///
   /// See also:
   ///
-  /// * [UIColor.systemGray5](https://developer.apple.com/documentation/uikit/uicolor/3255074-systemgray5),
-  ///   the `UIKit` equivalent.
+  ///  * [UIColor.systemGray5](https://developer.apple.com/documentation/uikit/uicolor/3255074-systemgray5),
+  ///    the `UIKit` equivalent.
   static const CupertinoDynamicColor systemGrey5 = CupertinoDynamicColor.withBrightnessAndContrast(
     debugLabel: 'systemGrey5',
     color: Color.fromARGB(255, 229, 229, 234),
@@ -294,8 +294,8 @@ class CupertinoColors {
   ///
   /// See also:
   ///
-  /// * [UIColor.systemGray6](https://developer.apple.com/documentation/uikit/uicolor/3255075-systemgray6),
-  ///   the `UIKit` equivalent.
+  ///  * [UIColor.systemGray6](https://developer.apple.com/documentation/uikit/uicolor/3255075-systemgray6),
+  ///    the `UIKit` equivalent.
   static const CupertinoDynamicColor systemGrey6 = CupertinoDynamicColor.withBrightnessAndContrast(
     debugLabel: 'systemGrey6',
     color: Color.fromARGB(255, 242, 242, 247),
@@ -667,10 +667,10 @@ class CupertinoColors {
 ///
 /// See also:
 ///
-/// * [CupertinoUserInterfaceLevel], an [InheritedWidget] that may affect color
-///   resolution of a [CupertinoDynamicColor].
-/// * [CupertinoTheme.of], a static method that retrieves the ambient [CupertinoThemeData],
-///   and then resolves [CupertinoDynamicColor]s used in the retrieved data.
+///  * [CupertinoUserInterfaceLevel], an [InheritedWidget] that may affect color
+///    resolution of a [CupertinoDynamicColor].
+///  * [CupertinoTheme.of], a static method that retrieves the ambient [CupertinoThemeData],
+///    and then resolves [CupertinoDynamicColor]s used in the retrieved data.
 @immutable
 class CupertinoDynamicColor extends Color with DiagnosticableMixin implements Diagnosticable {
   /// Creates an adaptive [Color] that changes its effective color based on the

packages/flutter/lib/src/cupertino/context_menu.dart

@@ -118,7 +118,7 @@ enum _ContextMenuLocation {
 ///
 /// See also:
 ///
-///   * [Apple's HIG for Context Menus](https://developer.apple.com/design/human-interface-guidelines/ios/controls/context-menus/)
+///  * [Apple's HIG for Context Menus](https://developer.apple.com/design/human-interface-guidelines/ios/controls/context-menus/)
 class CupertinoContextMenu extends StatefulWidget {
   /// Create a context menu.
   ///

packages/flutter/lib/src/cupertino/interface_level.dart

@@ -11,7 +11,7 @@ import '../widgets/framework.dart';
 ///
 /// See also:
 ///
-/// * `UIUserInterfaceLevel`, the UIKit equivalent: https://developer.apple.com/documentation/uikit/uiuserinterfacelevel.
+///  * `UIUserInterfaceLevel`, the UIKit equivalent: https://developer.apple.com/documentation/uikit/uiuserinterfacelevel.
 enum CupertinoUserInterfaceLevelData {
   /// The level for your window's main content.
   base,
@@ -33,8 +33,8 @@ enum CupertinoUserInterfaceLevelData {
 ///
 /// See also:
 ///
-/// * [CupertinoUserInterfaceLevelData], specifies the visual level for the content
-/// in the subtree [CupertinoUserInterfaceLevel] established.
+///  * [CupertinoUserInterfaceLevelData], specifies the visual level for the content
+///    in the subtree [CupertinoUserInterfaceLevel] established.
 class CupertinoUserInterfaceLevel extends InheritedWidget {
   /// Creates a [CupertinoUserInterfaceLevel] to change descendant Cupertino widget's
   /// visual level.

packages/flutter/lib/src/cupertino/tab_scaffold.dart

@@ -59,8 +59,8 @@ import 'theme.dart';
 ///
 /// See also:
 ///
-/// * [CupertinoTabScaffold], a tabbed application root layout that can be
-///   controlled by a [CupertinoTabController].
+///  * [CupertinoTabScaffold], a tabbed application root layout that can be
+///    controlled by a [CupertinoTabController].
 class CupertinoTabController extends ChangeNotifier {
   /// Creates a [CupertinoTabController] to control the tab index of [CupertinoTabScaffold]
   /// and [CupertinoTabBar].

packages/flutter/lib/src/cupertino/text_selection.dart

@@ -60,8 +60,8 @@ const EdgeInsets _kToolbarButtonPadding = EdgeInsets.symmetric(vertical: 10.0, h
 ///
 /// See also:
 ///
-/// * [TextSelectionControls.buildToolbar], where [CupertinoTextSelectionToolbar]
-///   will be used to build an iOS-style toolbar.
+///  * [TextSelectionControls.buildToolbar], where [CupertinoTextSelectionToolbar]
+///    will be used to build an iOS-style toolbar.
 @visibleForTesting
 class CupertinoTextSelectionToolbar extends SingleChildRenderObjectWidget {
   const CupertinoTextSelectionToolbar._({

packages/flutter/lib/src/cupertino/theme.dart

@@ -202,8 +202,8 @@ class CupertinoThemeData extends Diagnosticable {
   ///
   /// See also:
   ///
-  /// * [MaterialBasedCupertinoThemeData], a [CupertinoThemeData] that defers
-  ///   [brightness] to its Material [Theme] parent if it's unspecified.
+  ///  * [MaterialBasedCupertinoThemeData], a [CupertinoThemeData] that defers
+  ///    [brightness] to its Material [Theme] parent if it's unspecified.
   Brightness get brightness => _brightness ?? Brightness.light;
   final Brightness _brightness;
 
@@ -220,8 +220,8 @@ class CupertinoThemeData extends Diagnosticable {
   ///
   /// See also:
   ///
-  /// * [MaterialBasedCupertinoThemeData], a [CupertinoThemeData] that defers
-  ///   [primaryColor] to its Material [Theme] parent if it's unspecified.
+  ///  * [MaterialBasedCupertinoThemeData], a [CupertinoThemeData] that defers
+  ///    [primaryColor] to its Material [Theme] parent if it's unspecified.
   Color get primaryColor => _primaryColor ?? _defaults.primaryColor;
   final Color _primaryColor;
 
@@ -235,8 +235,8 @@ class CupertinoThemeData extends Diagnosticable {
   ///
   /// See also:
   ///
-  /// * [MaterialBasedCupertinoThemeData], a [CupertinoThemeData] that defers
-  ///   [primaryContrastingColor] to its Material [Theme] parent if it's unspecified.
+  ///  * [MaterialBasedCupertinoThemeData], a [CupertinoThemeData] that defers
+  ///    [primaryContrastingColor] to its Material [Theme] parent if it's unspecified.
   Color get primaryContrastingColor => _primaryContrastingColor ?? _defaults.primaryContrastingColor;
   final Color _primaryContrastingColor;
 

packages/flutter/lib/src/foundation/assertions.dart

@@ -92,12 +92,12 @@ abstract class _ErrorDiagnostic extends DiagnosticsProperty<List<Object>> {
 ///
 /// See also:
 ///
-/// * [ErrorSummary], which provides a short (one line) description of the
-///   problem that was detected.
-/// * [ErrorHint], which provides specific, non-obvious advice that may be
-///   applicable.
-/// * [FlutterError], which is the most common place to use an
-///   [ErrorDescription].
+///  * [ErrorSummary], which provides a short (one line) description of the
+///    problem that was detected.
+///  * [ErrorHint], which provides specific, non-obvious advice that may be
+///    applicable.
+///  * [FlutterError], which is the most common place to use an
+///    [ErrorDescription].
 class ErrorDescription extends _ErrorDiagnostic {
   /// A lint enforces that this constructor can only be called with a string
   /// literal to match the limitations of the Dart Kernel transformer that
@@ -126,12 +126,12 @@ class ErrorDescription extends _ErrorDiagnostic {
 ///
 /// See also:
 ///
-/// * [ErrorDescription], which provides an explanation of the problem and its
-///   cause, any information that may help track down the problem, background
-///   information, etc.
-/// * [ErrorHint], which provides specific, non-obvious advice that may be
-///   applicable.
-/// * [FlutterError], which is the most common place to use an [ErrorSummary].
+///  * [ErrorDescription], which provides an explanation of the problem and its
+///    cause, any information that may help track down the problem, background
+///    information, etc.
+///  * [ErrorHint], which provides specific, non-obvious advice that may be
+///    applicable.
+///  * [FlutterError], which is the most common place to use an [ErrorSummary].
 class ErrorSummary extends _ErrorDiagnostic {
   /// A lint enforces that this constructor can only be called with a string
   /// literal to match the limitations of the Dart Kernel transformer that
@@ -156,12 +156,12 @@ class ErrorSummary extends _ErrorDiagnostic {
 ///
 /// See also:
 ///
-/// * [ErrorSummary], which provides a short (one line) description of the
-///   problem that was detected.
-/// * [ErrorDescription], which provides an explanation of the problem and its
-///   cause, any information that may help track down the problem, background
-///   information, etc.
-/// * [FlutterError], which is the most common place to use an [ErrorHint].
+///  * [ErrorSummary], which provides a short (one line) description of the
+///    problem that was detected.
+///  * [ErrorDescription], which provides an explanation of the problem and its
+///    cause, any information that may help track down the problem, background
+///    information, etc.
+///  * [FlutterError], which is the most common place to use an [ErrorHint].
 class ErrorHint extends _ErrorDiagnostic {
   /// A lint enforces that this constructor can only be called with a string
   /// literal to match the limitations of the Dart Kernel transformer that

packages/flutter/lib/src/foundation/basic_types.dart

@@ -11,7 +11,9 @@ export 'dart:ui' show VoidCallback;
 
 /// Signature for callbacks that report that an underlying value has changed.
 ///
-/// See also [ValueSetter].
+/// See also:
+///
+///  * [ValueSetter], for callbacks that report that a value has been set.
 typedef ValueChanged<T> = void Function(T value);
 
 /// Signature for callbacks that report that a value has been set.

packages/flutter/lib/src/foundation/diagnostics.dart

@@ -158,6 +158,7 @@ enum DiagnosticsTreeStyle {
   /// the following line.
   ///
   /// See also:
+  ///
   ///  * [singleLine], which displays the same information but keeps the
   ///    property and value on the same line.
   errorProperty,
@@ -512,7 +513,7 @@ final TextTreeConfiguration denseTextConfiguration = TextTreeConfiguration(
 ///    ╚═══════════
 /// ```
 ///
-/// /// See also:
+/// See also:
 ///
 ///  * [DiagnosticsTreeStyle.transition], uses this style for ASCII art display.
 final TextTreeConfiguration transitionTextConfiguration = TextTreeConfiguration(
@@ -1058,7 +1059,7 @@ bool _isSingleLine(DiagnosticsTreeStyle style) {
 ///
 /// See also:
 ///
-/// * [DiagnosticsNode.toStringDeep], which uses a [TextTreeRenderer] to return a
+///  * [DiagnosticsNode.toStringDeep], which uses a [TextTreeRenderer] to return a
 ///    string representation of this node and its descendants.
 class TextTreeRenderer {
   /// Creates a [TextTreeRenderer] object with the given arguments specifying

packages/flutter/lib/src/foundation/key.dart

@@ -17,7 +17,9 @@ import 'package:meta/meta.dart';
 ///
 /// Subclasses of [Key] should either subclass [LocalKey] or [GlobalKey].
 ///
-/// See also the discussion at [Widget.key].
+/// See also:
+///
+///  * [Widget.key], which discusses how widgets use keys.
 @immutable
 abstract class Key {
   /// Construct a [ValueKey<String>] with the given [String].
@@ -38,7 +40,9 @@ abstract class Key {
 /// Keys must be unique amongst the [Element]s with the same parent. By
 /// contrast, [GlobalKey]s must be unique across the entire app.
 ///
-/// See also the discussion at [Widget.key].
+/// See also:
+///
+///  * [Widget.key], which discusses how widgets use keys.
 abstract class LocalKey extends Key {
   /// Default constructor, used by subclasses.
   const LocalKey() : super.empty();
@@ -55,7 +59,9 @@ abstract class LocalKey extends Key {
 /// other sources, which could be useful, for example, if the keys are being
 /// used as fallbacks in the same scope as keys supplied from another widget.
 ///
-/// See also the discussion at [Widget.key].
+/// See also:
+///
+///  * [Widget.key], which discusses how widgets use keys.
 class ValueKey<T> extends LocalKey {
   /// Creates a key that delegates its [operator==] to the given value.
   const ValueKey(this.value);

packages/flutter/lib/src/foundation/synchronous_future.dart

@@ -17,7 +17,10 @@ import 'dart:async';
 class SynchronousFuture<T> implements Future<T> {
   /// Creates a synchronous future.
   ///
-  /// See also [new Future.value].
+  /// See also:
+  ///
+  ///  * [new Future.value] for information about creating a regular
+  ///    [Future] that completes with a value.
   SynchronousFuture(this._value);
 
   final T _value;

packages/flutter/lib/src/gestures/binding.dart

@@ -229,8 +229,10 @@ mixin GestureBinding on BindingBase implements HitTestable, HitTestDispatcher, H
 /// Variant of [FlutterErrorDetails] with extra fields for the gesture
 /// library's binding's pointer event dispatcher ([GestureBinding.dispatchEvent]).
 ///
-/// See also [FlutterErrorDetailsForPointerRouter], which is also used by the
-/// gesture library.
+/// See also:
+///
+///  * [FlutterErrorDetailsForPointerRouter], which is also used by the
+///    gesture library.
 class FlutterErrorDetailsForPointerEventDispatcher extends FlutterErrorDetails {
   /// Creates a [FlutterErrorDetailsForPointerEventDispatcher] object with the given
   /// arguments setting the object's properties.

packages/flutter/lib/src/gestures/events.dart

@@ -150,7 +150,7 @@ int nthStylusButton(int number) => (kPrimaryStylusButton << (number - 1)) & kMax
 ///
 /// See also:
 ///
-///   * [isSingleButton], which checks if a `buttons` contains exactly one button.
+///  * [isSingleButton], which checks if a `buttons` contains exactly one button.
 int smallestButton(int buttons) => buttons & (-buttons);
 
 /// Returns whether `buttons` contains one and only one button.
@@ -170,8 +170,8 @@ int smallestButton(int buttons) => buttons & (-buttons);
 ///
 /// See also:
 ///
-///   * [smallestButton], which returns the button in a `buttons` bit field with
-///     the smallest integer button.
+///  * [smallestButton], which returns the button in a `buttons` bit field with
+///    the smallest integer button.
 bool isSingleButton(int buttons) => buttons != 0 && (smallestButton(buttons) == buttons);
 
 /// Base class for touch, stylus, or mouse events.

packages/flutter/lib/src/gestures/hit_test.dart

@@ -126,6 +126,7 @@ class HitTestResult {
   /// [popTransform] has to be called to remove the child-specific `transform`.
   ///
   /// See also:
+  ///
   ///  * [BoxHitTestResult.addWithPaintTransform], which is a public wrapper
   ///    around this function for hit testing on [RenderBox]s.
   ///  * [SliverHitTestResult.addWithAxisOffset], which is a public wrapper

packages/flutter/lib/src/gestures/pointer_router.dart

@@ -123,8 +123,10 @@ class PointerRouter {
 /// Variant of [FlutterErrorDetails] with extra fields for the gestures
 /// library's pointer router ([PointerRouter]).
 ///
-/// See also [FlutterErrorDetailsForPointerEventDispatcher], which is also used
-/// by the gestures library.
+/// See also:
+///
+///  * [FlutterErrorDetailsForPointerEventDispatcher], which is also used
+///    by the gestures library.
 class FlutterErrorDetailsForPointerRouter extends FlutterErrorDetails {
   /// Creates a [FlutterErrorDetailsForPointerRouter] object with the given
   /// arguments setting the object's properties.

packages/flutter/lib/src/gestures/recognizer.dart

@@ -32,7 +32,7 @@ typedef RecognizerCallback<T> = T Function();
 ///
 /// See also:
 ///
-///   * [DragGestureRecognizer.dragStartBehavior], which gives an example for the different behaviors.
+///  * [DragGestureRecognizer.dragStartBehavior], which gives an example for the different behaviors.
 enum DragStartBehavior {
   /// Set the initial offset, at the position where the first down event was
   /// detected.

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

@@ -308,10 +308,10 @@ class MaterialApp extends StatefulWidget {
   ///
   /// See also:
   ///
-  ///   * [theme], which is used when a light mode is selected.
-  ///   * [darkTheme], which is used when a dark mode is selected.
-  ///   * [ThemeData.brightness], which indicates to various parts of the
-  ///     system what kind of theme is being used.
+  ///  * [theme], which is used when a light mode is selected.
+  ///  * [darkTheme], which is used when a dark mode is selected.
+  ///  * [ThemeData.brightness], which indicates to various parts of the
+  ///    system what kind of theme is being used.
   final ThemeMode themeMode;
 
   /// {@macro flutter.widgets.widgetsApp.color}

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

@@ -186,7 +186,7 @@ class RawMaterialButton extends StatefulWidget {
   ///
   ///  * [elevation], the default elevation.
   ///  * [hoverElevation], the elevation when a pointer is hovering over the
-  ///  button.
+  ///    button.
   ///  * [focusElevation], the elevation when the button is focused.
   ///  * [disabledElevation], the elevation when the button is disabled.
   final double highlightElevation;
@@ -200,7 +200,7 @@ class RawMaterialButton extends StatefulWidget {
   ///
   ///  * [elevation], the default elevation.
   ///  * [hoverElevation], the elevation when a pointer is hovering over the
-  ///  button.
+  ///    button.
   ///  * [focusElevation], the elevation when the button is focused.
   ///  * [highlightElevation], the elevation when the button is pressed.
   final double disabledElevation;

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

@@ -20,10 +20,10 @@ import 'theme.dart';
 ///
 /// See also:
 ///
-///   * [ButtonBarTheme], an [InheritedWidget] that propagates the theme down
-///     its subtree.
-///   * [ButtonBar], which uses this to configure itself and its children
-///     button widgets.
+///  * [ButtonBarTheme], an [InheritedWidget] that propagates the theme down
+///    its subtree.
+///  * [ButtonBar], which uses this to configure itself and its children
+///    button widgets.
 class ButtonBarThemeData extends Diagnosticable {
   /// Constructs the set of properties used to configure [ButtonBar] widgets.
   ///

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

@@ -30,9 +30,9 @@ class ElevationOverlay {
   ///
   /// See also:
   ///
-  ///   * [ThemeData.applyElevationOverlayColor] which controls the whether
-  ///     an overlay color will be applied to indicate elevation.
-  ///   * [overlayColor] which computes the needed overlay color.
+  ///  * [ThemeData.applyElevationOverlayColor] which controls the whether
+  ///    an overlay color will be applied to indicate elevation.
+  ///  * [overlayColor] which computes the needed overlay color.
   static Color applyOverlay(BuildContext context, Color color, double elevation) {
     final ThemeData theme = Theme.of(context);
     if (elevation > 0.0 &&
@@ -49,8 +49,8 @@ class ElevationOverlay {
   ///
   /// See also:
   ///
-  ///   * https://material.io/design/color/dark-theme.html#properties which
-  ///     specifies the exact overlay values for a given elevation.
+  ///  * https://material.io/design/color/dark-theme.html#properties which
+  ///    specifies the exact overlay values for a given elevation.
   static Color overlayColor(BuildContext context, double elevation) {
     final ThemeData theme = Theme.of(context);
     // Compute the opacity for the given elevation

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

@@ -216,8 +216,6 @@ class IconButton extends StatelessWidget {
   ///
   /// The icon is enabled if [onPressed] is not null.
   ///
-  /// See also [disabledColor].
-  ///
   /// ```dart
   /// IconButton(
   ///   color: Colors.blue,
@@ -249,8 +247,6 @@ class IconButton extends StatelessWidget {
   /// Defaults to the [ThemeData.disabledColor] of the current [Theme].
   ///
   /// The icon is disabled if [onPressed] is null.
-  ///
-  /// See also [color].
   final Color disabledColor;
 
   /// The callback that is called when the button is tapped or otherwise activated.

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

@@ -1787,7 +1787,7 @@ class InputDecorator extends StatefulWidget {
   ///
   /// See also:
   ///
-  ///  - [InputDecoration.hoverColor], which is also blended into the focus
+  ///  * [InputDecoration.hoverColor], which is also blended into the focus
   ///    color and fill color when the [isHovering] is true to produce the final
   ///    color.
   final bool isFocused;
@@ -1802,7 +1802,7 @@ class InputDecorator extends StatefulWidget {
   ///
   /// See also:
   ///
-  ///  - [InputDecoration.focusColor], which is also blended into the hover
+  ///  * [InputDecoration.focusColor], which is also blended into the hover
   ///    color and fill color when [isFocused] is true to produce the final
   ///    color.
   final bool isHovering;

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

@@ -214,9 +214,9 @@ class Material extends StatefulWidget {
   ///
   /// See also:
   ///
-  ///   * [ThemeData.applyElevationOverlayColor] which controls the whether
-  ///     an overlay color will be applied to indicate elevation.
-  ///   * [color] which may have an elevation overlay applied.
+  ///  * [ThemeData.applyElevationOverlayColor] which controls the whether
+  ///    an overlay color will be applied to indicate elevation.
+  ///  * [color] which may have an elevation overlay applied.
   ///
   /// {@endtemplate}
   final double elevation;

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

@@ -12,6 +12,7 @@ import 'dart:ui' show Color;
 /// Some Material widgets track their current state in a `Set<MaterialState>`.
 ///
 /// See also:
+///
 ///  * [MaterialStateColor], a color that has a `resolve` method that can
 ///    return a different color depending on the state of the widget that it
 ///    is used in.

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

@@ -1448,16 +1448,16 @@ abstract class RangeSliderTrackShape {
 /// Base track shape that provides an implementation of [getPreferredRect] for
 /// default sizing.
 ///
+/// The height is set from [SliderThemeData.trackHeight] and the width of the
+/// parent box less the larger of the widths of [SliderThemeData.thumbShape] and
+/// [SliderThemeData.overlayShape].
+///
 /// See also:
 ///
 ///  * [RectangularSliderTrackShape], which is a track shape with sharp
 ///    rectangular edges
 ///  * [RoundedRectSliderTrackShape], which is a track shape with round
 ///    stadium-like edges.
-///
-/// The height is set from [SliderThemeData.trackHeight] and the width of the
-/// parent box less the larger of the widths of [SliderThemeData.thumbShape] and
-/// [SliderThemeData.overlayShape].
 abstract class BaseSliderTrackShape {
   /// Returns a rect that represents the track bounds that fits within the
   /// [Slider].

packages/flutter/lib/src/painting/box_fit.dart

@@ -10,8 +10,10 @@ import 'basic_types.dart';
 
 /// How a box should be inscribed into another box.
 ///
-/// See also [applyBoxFit], which applies the sizing semantics of these values
-/// (though not the alignment semantics).
+/// See also:
+///
+///  * [applyBoxFit], which applies the sizing semantics of these values (though
+///    not the alignment semantics).
 enum BoxFit {
   /// Fill the target box by distorting the source's aspect ratio.
   ///

packages/flutter/lib/src/painting/continuous_rectangle_border.dart

@@ -26,10 +26,10 @@ import 'edge_insets.dart';
 ///
 /// See also:
 ///
-/// * [RoundedRectangleBorder] Which creates rectangles with rounded corners,
-///   however its straight sides change into a rounded corner with a circular
-///   radius in a step function instead of gradually like the
-///   [ContinuousRectangleBorder].
+///  * [RoundedRectangleBorder] Which creates rectangles with rounded corners,
+///    however its straight sides change into a rounded corner with a circular
+///    radius in a step function instead of gradually like the
+///    [ContinuousRectangleBorder].
 class ContinuousRectangleBorder extends ShapeBorder {
   /// The arguments must not be null.
   const ContinuousRectangleBorder({

packages/flutter/lib/src/painting/image_provider.dart

@@ -398,7 +398,7 @@ abstract class ImageProvider<T> {
   ///
   /// See also:
   ///
-  ///   * [ResizeImage], for modifying the key to account for cache dimensions.
+  ///  * [ResizeImage], for modifying the key to account for cache dimensions.
   @protected
   ImageStreamCompleter load(T key, DecoderCallback decode);
 

packages/flutter/lib/src/painting/inline_span.dart

@@ -40,7 +40,8 @@ typedef InlineSpanVisitor = bool Function(InlineSpan span);
 /// For [PlaceholderSpan]s, [InlineSpanSemanticsInformation.placeholder] is used by default.
 ///
 /// See also:
-///   * [InlineSpan.getSemanticsInformation]
+///
+///  * [InlineSpan.getSemanticsInformation]
 @immutable
 class InlineSpanSemanticsInformation {
   /// Constructs an object that holds the text and semantics label values of an

packages/flutter/lib/src/rendering/binding.dart

@@ -466,8 +466,6 @@ void debugDumpSemanticsTree(DebugSemanticsDumpOrder childOrder) {
 /// rendering layer directly. If you are writing to a higher-level
 /// library, such as the Flutter Widgets library, then you would use
 /// that layer's binding.
-///
-/// See also [BindingBase].
 class RenderingFlutterBinding extends BindingBase with GestureBinding, ServicesBinding, SchedulerBinding, SemanticsBinding, PaintingBinding, RendererBinding {
   /// Creates a binding for the rendering layer.
   ///

packages/flutter/lib/src/rendering/box.dart

@@ -273,8 +273,10 @@ class BoxConstraints extends Constraints {
   /// Returns the size that both satisfies the constraints and is as close as
   /// possible to the given size.
   ///
-  /// See also [constrainDimensions], which applies the same algorithm to
-  /// separately provided widths and heights.
+  /// See also:
+  ///
+  ///  * [constrainDimensions], which applies the same algorithm to
+  ///    separately provided widths and heights.
   Size constrain(Size size) {
     Size result = Size(constrainWidth(size.width), constrainHeight(size.height));
     assert(() {
@@ -1511,7 +1513,9 @@ abstract class RenderBox extends RenderObject {
   ///
   /// This function should never return a negative or infinite value.
   ///
-  /// See also examples in the definition of [computeMinIntrinsicWidth].
+  /// See also:
+  ///
+  ///  * [computeMinIntrinsicWidth], which has usage examples.
   @protected
   double computeMaxIntrinsicWidth(double height) {
     return 0.0;
@@ -1585,7 +1589,9 @@ abstract class RenderBox extends RenderObject {
   ///
   /// This function should never return a negative or infinite value.
   ///
-  /// See also examples in the definition of [computeMinIntrinsicWidth].
+  /// See also:
+  ///
+  ///  * [computeMinIntrinsicWidth], which has usage examples.
   @protected
   double computeMinIntrinsicHeight(double width) {
     return 0.0;
@@ -1664,7 +1670,9 @@ abstract class RenderBox extends RenderObject {
   ///
   /// This function should never return a negative or infinite value.
   ///
-  /// See also examples in the definition of [computeMinIntrinsicWidth].
+  /// See also:
+  ///
+  ///  * [computeMinIntrinsicWidth], which has usage examples.
   @protected
   double computeMaxIntrinsicHeight(double width) {
     return 0.0;

packages/flutter/lib/src/rendering/sliver_persistent_header.dart

@@ -22,7 +22,7 @@ import 'viewport_offset.dart';
 /// See also:
 ///
 ///  * [SliverAppBar], which creates a header that can be stretched into an
-///  overscroll area and trigger a callback function.
+///    overscroll area and trigger a callback function.
 class OverScrollHeaderStretchConfiguration {
   /// Creates an object that specifies how a stretched header may activate an
   /// [AsyncCallback].
@@ -111,7 +111,7 @@ abstract class RenderSliverPersistentHeader extends RenderSliver with RenderObje
   /// See also:
   ///
   ///  * [SliverAppBar], which creates a header that can stretched into an
-  ///  overscroll area and trigger a callback function.
+  ///    overscroll area and trigger a callback function.
   OverScrollHeaderStretchConfiguration stretchConfiguration;
 
   /// Update the child render object if necessary.

packages/flutter/lib/src/rendering/view.dart

@@ -193,8 +193,8 @@ class RenderView extends RenderObject with RenderObjectWithChildMixin<RenderBox>
   ///
   /// See also:
   ///
-  /// * [Layer.findAllAnnotations], which is used by this method to find all
-  ///   [AnnotatedRegionLayer]s annotated for mouse tracking.
+  ///  * [Layer.findAllAnnotations], which is used by this method to find all
+  ///    [AnnotatedRegionLayer]s annotated for mouse tracking.
   Iterable<MouseTrackerAnnotation> hitTestMouseTrackers(Offset position) {
     // Layer hit testing is done using device pixels, so we have to convert
     // the logical coordinates of the event location back to device pixels

packages/flutter/lib/src/rendering/viewport.dart

@@ -800,8 +800,10 @@ abstract class RenderViewportBase<ParentDataClass extends ContainerParentDataMix
   /// viewport to the top left corner of the paint coordinate system of the
   /// `child`.
   ///
-  /// See also [paintOffsetOf], which uses the layout offset and growth
-  /// direction computed for the child during layout.
+  /// See also:
+  ///
+  ///  * [paintOffsetOf], which uses the layout offset and growth direction
+  ///    computed for the child during layout.
   @protected
   Offset computeAbsolutePaintOffset(RenderSliver child, double layoutOffset, GrowthDirection growthDirection) {
     assert(hasSize); // this is only usable once we have a size
@@ -886,9 +888,11 @@ abstract class RenderViewportBase<ParentDataClass extends ContainerParentDataMix
   /// viewport to the top left corner of the paint coordinate system of the
   /// `child`.
   ///
-  /// See also [computeAbsolutePaintOffset], which computes the paint offset
-  /// from an explicit layout offset and growth direction instead of using the
-  /// values computed for the child during layout.
+  /// See also:
+  ///
+  ///  * [computeAbsolutePaintOffset], which computes the paint offset from an
+  ///    explicit layout offset and growth direction instead of using the values
+  ///    computed for the child during layout.
   @protected
   Offset paintOffsetOf(RenderSliver child);
 

packages/flutter/lib/src/scheduler/binding.dart

@@ -50,10 +50,12 @@ typedef TaskCallback<T> = T Function();
 /// whenever the system needs to decide whether a task at a given
 /// priority needs to be run.
 ///
-/// Return true if a task with the given priority should be executed
-/// at this time, false otherwise.
+/// Return true if a task with the given priority should be executed at this
+/// time, false otherwise.
 ///
-/// See also [defaultSchedulingStrategy].
+/// See also:
+///
+///  * [defaultSchedulingStrategy], the default [SchedulingStrategy] for [SchedulerBinding.schedulingStrategy].
 typedef SchedulingStrategy = bool Function({ int priority, SchedulerBinding scheduler });
 
 class _TaskEntry<T> {
@@ -133,7 +135,10 @@ class _FrameCallbackEntry {
 /// The values of this enum are ordered in the same order as the phases occur,
 /// so their relative index values can be compared to each other.
 ///
-/// See also the discussion at [WidgetsBinding.drawFrame].
+/// See also:
+///
+///  * [WidgetsBinding.drawFrame], which pumps the build and rendering pipeline
+///    to generate a frame.
 enum SchedulerPhase {
   /// No frame is being processed. Tasks (scheduled by
   /// [WidgetsBinding.scheduleTask]), microtasks (scheduled by

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

@@ -4006,7 +4006,7 @@ String _concatStrings({
 /// nodes, it is recommended to either use comparable keys for all nodes, or
 /// use null for all of them, leaving the sort order to the default algorithm.
 ///
-/// See Also:
+/// See also:
 ///
 ///  * [OrdinalSortKey] for a sort key that sorts using an ordinal.
 abstract class SemanticsSortKey extends Diagnosticable implements Comparable<SemanticsSortKey> {

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

@@ -141,11 +141,13 @@ class TapSemanticEvent extends SemanticsEvent {
 /// the label of the semantics node has changed since the last live region
 /// update. iOS does not currently support this event.
 ///
+/// Deprecated. This message was never implemented, and references to it should
+/// be removed.
+///
 /// See also:
 ///
 ///  * [SemanticsFlag.liveRegion], for a description of live regions.
 ///
-/// Deprecated. This message was never implemented, and references to it should be removed.
 @Deprecated(
   'This event has never been implemented and will be removed in a future version of Flutter. References to it should be removed. '
   'This feature was deprecated after v1.12.16.'

packages/flutter/lib/src/services/platform_views.dart

@@ -19,10 +19,6 @@ final PlatformViewsRegistry platformViewsRegistry = PlatformViewsRegistry._insta
 ///
 /// A Flutter application has a single [PlatformViewsRegistry] which can be accesses
 /// through the [platformViewsRegistry] getter.
-///
-/// See also:
-///
-///  * [PlatformView], a widget that shows a platform view.
 class PlatformViewsRegistry {
   PlatformViewsRegistry._instance();
 
@@ -48,8 +44,6 @@ typedef PlatformViewCreatedCallback = void Function(int id);
 /// Provides access to the platform views service.
 ///
 /// This service allows creating and controlling platform-specific views.
-///
-/// See also: [PlatformView].
 class PlatformViewsService {
   PlatformViewsService._() {
     SystemChannels.platform_views.setMethodCallHandler(_onMethodCall);
@@ -724,7 +718,9 @@ abstract class PlatformViewController {
   ///
   /// The viewId should always be unique and non-negative. And it must not be null.
   ///
-  /// See also [PlatformViewRegistry] which is a helper for managing platform view ids.
+  /// See also:
+  ///
+  ///  * [PlatformViewRegistry], which is a helper for managing platform view ids.
   int get viewId;
 
   /// Dispatches the `event` to the platform view.

packages/flutter/lib/src/services/raw_keyboard_macos.dart

@@ -35,7 +35,7 @@ class RawKeyEventDataMacOs extends RawKeyEventData {
   ///
   /// See also:
   ///
-  ///   * [Apple's NSEvent documentation](https://developer.apple.com/documentation/appkit/nsevent/1534183-characters?language=objc)
+  ///  * [Apple's NSEvent documentation](https://developer.apple.com/documentation/appkit/nsevent/1534183-characters?language=objc)
   final String characters;
 
   /// The characters generated by a key event as if no modifier key (except for
@@ -43,21 +43,21 @@ class RawKeyEventDataMacOs extends RawKeyEventData {
   ///
   /// See also:
   ///
-  ///   * [Apple's NSEvent documentation](https://developer.apple.com/documentation/appkit/nsevent/1524605-charactersignoringmodifiers?language=objc)
+  ///  * [Apple's NSEvent documentation](https://developer.apple.com/documentation/appkit/nsevent/1524605-charactersignoringmodifiers?language=objc)
   final String charactersIgnoringModifiers;
 
   /// The virtual key code for the keyboard key associated with a key event.
   ///
   /// See also:
   ///
-  ///   * [Apple's NSEvent documentation](https://developer.apple.com/documentation/appkit/nsevent/1534513-keycode?language=objc)
+  ///  * [Apple's NSEvent documentation](https://developer.apple.com/documentation/appkit/nsevent/1534513-keycode?language=objc)
   final int keyCode;
 
   /// A mask of the current modifiers using the values in Modifier Flags.
   ///
   /// See also:
   ///
-  ///   * [Apple's NSEvent documentation](https://developer.apple.com/documentation/appkit/nsevent/1535211-modifierflags?language=objc)
+  ///  * [Apple's NSEvent documentation](https://developer.apple.com/documentation/appkit/nsevent/1535211-modifierflags?language=objc)
   final int modifiers;
 
   @override

packages/flutter/lib/src/services/system_channels.dart

@@ -22,25 +22,22 @@ class SystemChannels {
   ///  * `pushRoute`, which is called with a single string argument when the
   ///    operating system instructs the application to open a particular page.
   ///
-  /// See also:
-  ///
-  ///  * [WidgetsBindingObserver.didPopRoute] and
-  ///    [WidgetsBindingObserver.didPushRoute], which expose this channel's
-  ///    methods.
-  ///
   /// The following methods are used for the opposite direction data flow. The
   /// framework notifies the engine about the route changes.
   ///
   ///  * `routePushed`, which is called when a route is pushed. (e.g. A modal
-  ///  replaces the entire screen.)
+  ///    replaces the entire screen.)
   ///
   ///  * `routePopped`, which is called when a route is popped. (e.g. A dialog,
-  ///  such as time picker is closed.)
+  ///    such as time picker is closed.)
   ///
   ///  * `routeReplaced`, which is called when a route is replaced.
   ///
   /// See also:
   ///
+  ///  * [WidgetsBindingObserver.didPopRoute] and
+  ///    [WidgetsBindingObserver.didPushRoute], which expose this channel's
+  ///    methods.
   ///  * [Navigator] which manages transitions from one page to another.
   ///    [Navigator.push], [Navigator.pushReplacement], [Navigator.pop] and
   ///    [Navigator.replace], utilize this channel's methods to send route
@@ -251,7 +248,9 @@ class SystemChannels {
 
   /// A [MethodChannel] for controlling platform views.
   ///
-  /// See also: [PlatformViewsService] for the available operations on this channel.
+  /// See also:
+  ///
+  ///  * [PlatformViewsService] for the available operations on this channel.
   static const MethodChannel platform_views = MethodChannel(
     'flutter/platform_views',
     StandardMethodCodec(),

packages/flutter/lib/src/services/system_chrome.dart

@@ -380,7 +380,8 @@ class SystemChrome {
   /// {@end-tool}
   ///
   /// See also:
-  ///   * [AnnotatedRegion], the widget used to place data into the layer tree.
+  ///
+  ///  * [AnnotatedRegion], the widget used to place data into the layer tree.
   static void setSystemUIOverlayStyle(SystemUiOverlayStyle style) {
     assert(style != null);
     if (_pendingStyle != null) {

packages/flutter/lib/src/services/text_input.dart

@@ -421,6 +421,7 @@ class TextInputConfiguration {
   /// Defaults to true. Cannot be null.
   ///
   /// See also:
+  ///
   ///  * <https://developer.android.com/reference/android/text/InputType.html#TYPE_TEXT_FLAG_NO_SUGGESTIONS>
   /// {@endtemplate}
   final bool enableSuggestions;

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

@@ -67,11 +67,11 @@ class Intent extends Diagnosticable {
 ///
 /// See also:
 ///
-///  - [Shortcuts], which is a widget that contains a key map, in which it looks
+///  * [Shortcuts], which is a widget that contains a key map, in which it looks
 ///    up key combinations in order to invoke actions.
-///  - [Actions], which is a widget that defines a map of [Intent] to [Action]
+///  * [Actions], which is a widget that defines a map of [Intent] to [Action]
 ///    and allows redefining of actions for its descendants.
-///  - [ActionDispatcher], a class that takes an [Action] and invokes it using a
+///  * [ActionDispatcher], a class that takes an [Action] and invokes it using a
 ///    [FocusNode] for context.
 abstract class Action extends Diagnosticable {
   /// A const constructor for an [Action].
@@ -114,11 +114,11 @@ typedef OnInvokeCallback = void Function(FocusNode node, Intent tag);
 ///
 /// See also:
 ///
-///  - [Shortcuts], which is a widget that contains a key map, in which it looks
+///  * [Shortcuts], which is a widget that contains a key map, in which it looks
 ///    up key combinations in order to invoke actions.
-///  - [Actions], which is a widget that defines a map of [Intent] to [Action]
+///  * [Actions], which is a widget that defines a map of [Intent] to [Action]
 ///    and allows redefining of actions for its descendants.
-///  - [ActionDispatcher], a class that takes an [Action] and invokes it using a
+///  * [ActionDispatcher], a class that takes an [Action] and invokes it using a
 ///    [FocusNode] for context.
 class CallbackAction extends Action {
   /// A const constructor for an [Action].
@@ -173,12 +173,12 @@ class ActionDispatcher extends Diagnosticable {
 ///
 /// See also:
 ///
-///   * [ActionDispatcher], the object that this widget uses to manage actions.
-///   * [Action], a class for containing and defining an invocation of a user
-///     action.
-///   * [Intent], a class that holds a unique [LocalKey] identifying an action,
-///     as well as configuration information for running the [Action].
-///   * [Shortcuts], a widget used to bind key combinations to [Intent]s.
+///  * [ActionDispatcher], the object that this widget uses to manage actions.
+///  * [Action], a class for containing and defining an invocation of a user
+///    action.
+///  * [Intent], a class that holds a unique [LocalKey] identifying an action,
+///    as well as configuration information for running the [Action].
+///  * [Shortcuts], a widget used to bind key combinations to [Intent]s.
 class Actions extends InheritedWidget {
   /// Creates an [Actions] widget.
   ///

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

@@ -263,8 +263,8 @@ class _ActiveItem implements Comparable<_ActiveItem> {
 ///
 /// See also:
 ///
-/// * [SliverAnimatedList], a sliver that animates items when they are inserted
-///   or removed from a list.
+///  * [SliverAnimatedList], a sliver that animates items when they are inserted
+///    or removed from a list.
 class AnimatedList extends StatefulWidget {
   /// Creates a scrolling container that animates items when they are inserted
   /// or removed.
@@ -727,10 +727,10 @@ class AnimatedListState extends State<AnimatedList> with TickerProviderStateMixi
 ///
 /// See also:
 ///
-/// * [SliverList], which does not animate items when they are inserted or
-///   removed.
-/// * [AnimatedList], a non-sliver scrolling container that animates items when
-///   they are inserted or removed.
+///  * [SliverList], which does not animate items when they are inserted or
+///    removed.
+///  * [AnimatedList], a non-sliver scrolling container that animates items when
+///    they are inserted or removed.
 class SliverAnimatedList extends StatefulWidget {
   /// Creates a sliver that animates items when they are inserted or removed.
   const SliverAnimatedList({

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

@@ -91,15 +91,33 @@ typedef GenerateAppTitle = String Function(BuildContext context);
 /// Creates a [PageRoute] using the given [RouteSettings] and [WidgetBuilder].
 typedef PageRouteFactory = PageRoute<T> Function<T>(RouteSettings settings, WidgetBuilder builder);
 
-/// A convenience class that wraps a number of widgets that are commonly
+/// A convenience widget that wraps a number of widgets that are commonly
 /// required for an application.
 ///
 /// One of the primary roles that [WidgetsApp] provides is binding the system
 /// back button to popping the [Navigator] or quitting the application.
 ///
-/// See also: [CheckedModeBanner], [DefaultTextStyle], [MediaQuery],
-/// [Localizations], [Title], [Navigator], [Overlay], [SemanticsDebugger] (the
-/// widgets wrapped by this one).
+/// It is used by both [MaterialApp] and [CupertinoApp] to implement base
+/// functionality for an app.
+///
+/// Find references to many of the widgets that [WidgetsApp] wraps in the "See
+/// also" section.
+///
+/// See also:
+///
+///  * [CheckedModeBanner], which displays a [Banner] saying "DEBUG" when
+///    running in checked mode.
+///  * [DefaultTextStyle], the text style to apply to descendant [Text] widgets
+///    without an explicit style.
+///  * [MediaQuery], which establishes a subtree in which media queries resolve
+///    to a [MediaQueryData].
+///  * [Localizations], which defines the [Locale] for its `child`.
+///  * [Title], a widget that describes this app in the operating system.
+///  * [Navigator], a widget that manages a set of child widgets with a stack
+///    discipline.
+///  * [Overlay], a widget that manages a [Stack] of entries that can be managed
+///    independently.
+///  * [SemanticsDebugger], a widget that visualizes the semantics for the child.
 class WidgetsApp extends StatefulWidget {
   /// Creates a widget that wraps a number of widgets that are commonly
   /// required for an application.

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

@@ -84,8 +84,10 @@ class BannerPainter extends CustomPainter {
   /// context, the English phrase will be on the right and the Hebrew phrase on
   /// its left.
   ///
-  /// See also [layoutDirection], which controls the interpretation of values in
-  /// [location].
+  /// See also:
+  ///
+  ///  * [layoutDirection], which controls the interpretation of values in
+  ///    [location].
   final TextDirection textDirection;
 
   /// Where to show the banner (e.g., the upper right corner).
@@ -95,8 +97,9 @@ class BannerPainter extends CustomPainter {
   ///
   /// This value is used to interpret the [location] of the banner.
   ///
-  /// See also [textDirection], which controls the reading direction of the
-  /// [message].
+  /// See also:
+  ///
+  ///  * [textDirection], which controls the reading direction of the [message].
   final TextDirection layoutDirection;
 
   /// The color to paint behind the [message].
@@ -277,8 +280,9 @@ class Banner extends StatelessWidget {
   ///
   /// Defaults to the ambient [Directionality], if any.
   ///
-  /// See also [layoutDirection], which controls the interpretation of the
-  /// [location].
+  /// See also:
+  ///
+  ///  * [layoutDirection], which controls the interpretation of the [location].
   final TextDirection textDirection;
 
   /// Where to show the banner (e.g., the upper right corner).
@@ -290,8 +294,9 @@ class Banner extends StatelessWidget {
   ///
   /// Defaults to the ambient [Directionality], if any.
   ///
-  /// See also [textDirection], which controls the reading direction of the
-  /// [message].
+  /// See also:
+  ///
+  ///  * [textDirection], which controls the reading direction of the [message].
   final TextDirection layoutDirection;
 
   /// The color of the banner.
@@ -332,7 +337,7 @@ class Banner extends StatelessWidget {
 /// [MaterialApp] builds one of these by default.
 /// Does nothing in release mode.
 class CheckedModeBanner extends StatelessWidget {
-  /// Creates a checked mode banner.
+  /// Creates a const checked mode banner.
   const CheckedModeBanner({
     Key key,
     @required this.child,

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

@@ -815,7 +815,10 @@ mixin WidgetsBinding on BindingBase, ServicesBinding, SchedulerBinding, GestureB
   ///
   /// This is called by [runApp] to configure the widget tree.
   ///
-  /// See also [RenderObjectToWidgetAdapter.attachToRenderTree].
+  /// See also:
+  ///
+  ///  * [RenderObjectToWidgetAdapter.attachToRenderTree], which inflates a
+  ///    widget and attaches it to the render tree.
   void attachRootWidget(Widget rootWidget) {
     _renderViewElement = RenderObjectToWidgetAdapter<RenderBox>(
       container: renderView,

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

@@ -75,6 +75,6 @@ class BottomNavigationBarItem {
   /// See also:
   ///
   ///  * [Icon.color] and [ImageIcon.color] to control the foreground color of
-  ///     the icons themselves.
+  ///    the icons themselves.
   final Color backgroundColor;
 }

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

@@ -29,7 +29,10 @@ import 'table.dart';
 /// Observatory rather than getting it in the console (where it can be
 /// overwhelming), consider [debugProfileBuildsEnabled].
 ///
-/// See also the discussion at [WidgetsBinding.drawFrame].
+/// See also:
+///
+///  * [WidgetsBinding.drawFrame], which pumps the build and rendering pipeline
+///    to generate a frame.
 bool debugPrintRebuildDirtyWidgets = false;
 
 /// Signature for [debugOnRebuildDirtyWidget] implementations.
@@ -62,7 +65,10 @@ RebuildDirtyWidgetCallback debugOnRebuildDirtyWidget;
 /// triggered by the initial mounting of a widget tree (e.g. in a call to
 /// [runApp]) from the regular builds triggered by the pipeline.
 ///
-/// See also the discussion at [WidgetsBinding.drawFrame].
+/// See also:
+///
+///  * [WidgetsBinding.drawFrame], which pumps the build and rendering pipeline
+///    to generate a frame.
 bool debugPrintBuildScope = false;
 
 /// Log the call stacks that mark widgets as needing to be rebuilt.
@@ -90,9 +96,11 @@ bool debugPrintGlobalKeyedWidgetLifecycle = false;
 /// optimize your app, see https://flutter.dev/docs/testing/debugging#tracing-any-dart-code-performance
 /// and https://fuchsia.googlesource.com/topaz/+/master/shell/docs/performance.md
 ///
-/// See also [debugProfilePaintsEnabled], which does something similar but for
-/// painting, and [debugPrintRebuildDirtyWidgets], which does something similar
-/// but reporting the builds to the console.
+/// See also:
+///
+///  * [debugProfilePaintsEnabled], which does something similar but for
+///    painting, and [debugPrintRebuildDirtyWidgets], which does something similar
+///    but reporting the builds to the console.
 bool debugProfileBuildsEnabled = false;
 
 /// Show banners for deprecated widgets.

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

@@ -149,10 +149,14 @@ class Dismissible extends StatefulWidget {
   /// Flinging is treated as being equivalent to dragging almost to 1.0, so
   /// flinging can dismiss an item past any threshold less than 1.0.
   ///
-  /// See also [direction], which controls the directions in which the items can
-  /// be dismissed. Setting a threshold of 1.0 (or greater) prevents a drag in
-  /// the given [DismissDirection] even if it would be allowed by the
-  /// [direction] property.
+  /// Setting a threshold of 1.0 (or greater) prevents a drag in the given
+  /// [DismissDirection] even if it would be allowed by the [direction]
+  /// property.
+  ///
+  /// See also:
+  ///
+  ///  * [direction], which controls the directions in which the items can
+  ///    be dismissed.
   final Map<DismissDirection, double> dismissThresholds;
 
   /// Defines the duration for card to dismiss or to come back to original position if not dismissed.

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

@@ -579,7 +579,7 @@ class EditableText extends StatefulWidget {
   ///
   /// See also:
   ///
-  ///   * {@macro flutter.gestures.monodrag.dragStartExample}
+  ///  * {@macro flutter.gestures.monodrag.dragStartExample}
   ///
   /// {@endtemplate}
   final TextDirection textDirection;

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

@@ -351,18 +351,18 @@ class FocusAttachment {
 ///
 /// See also:
 ///
-///   * [Focus], a widget that manages a [FocusNode] and provides access to
-///     focus information and actions to its descendant widgets.
-///   * [FocusScope], a widget that manages a [FocusScopeNode] and provides
-///     access to scope information and actions to its descendant widgets.
-///   * [FocusAttachment], a widget that connects a [FocusScopeNode] to the
-///     widget tree.
-///   * [FocusManager], a singleton that manages the focus and distributes key
-///     events to focused nodes.
-///   * [FocusTraversalPolicy], a class used to determine how to move the focus
-///     to other nodes.
-///   * [DefaultFocusTraversal], a widget used to configure the default focus
-///     traversal policy for a widget subtree.
+///  * [Focus], a widget that manages a [FocusNode] and provides access to
+///    focus information and actions to its descendant widgets.
+///  * [FocusScope], a widget that manages a [FocusScopeNode] and provides
+///    access to scope information and actions to its descendant widgets.
+///  * [FocusAttachment], a widget that connects a [FocusScopeNode] to the
+///    widget tree.
+///  * [FocusManager], a singleton that manages the focus and distributes key
+///    events to focused nodes.
+///  * [FocusTraversalPolicy], a class used to determine how to move the focus
+///    to other nodes.
+///  * [DefaultFocusTraversal], a widget used to configure the default focus
+///    traversal policy for a widget subtree.
 class FocusNode with DiagnosticableTreeMixin, ChangeNotifier {
   /// Creates a focus node.
   ///
@@ -417,10 +417,10 @@ class FocusNode with DiagnosticableTreeMixin, ChangeNotifier {
   ///
   /// See also:
   ///
-  ///   - [DefaultFocusTraversal], a widget that sets the traversal policy for
-  ///     its descendants.
-  ///   - [FocusTraversalPolicy], a class that can be extended to describe a
-  ///     traversal policy.
+  ///  * [DefaultFocusTraversal], a widget that sets the traversal policy for
+  ///    its descendants.
+  ///  * [FocusTraversalPolicy], a class that can be extended to describe a
+  ///    traversal policy.
   bool get canRequestFocus {
     final FocusScopeNode scope = enclosingScope;
     return _canRequestFocus && (scope == null || scope.canRequestFocus);
@@ -548,8 +548,8 @@ class FocusNode with DiagnosticableTreeMixin, ChangeNotifier {
   ///
   /// See also:
   ///
-  ///   * [Focus.isAt], which is a static method that will return the focus
-  ///     state of the nearest ancestor [Focus] widget's focus node.
+  ///  * [Focus.isAt], which is a static method that will return the focus
+  ///    state of the nearest ancestor [Focus] widget's focus node.
   bool get hasFocus {
     if (_manager?.primaryFocus == null) {
       return false;
@@ -942,14 +942,14 @@ class FocusNode with DiagnosticableTreeMixin, ChangeNotifier {
 ///
 /// See also:
 ///
-///   * [Focus], a widget that manages a [FocusNode] and provides access to
-///     focus information and actions to its descendant widgets.
-///   * [FocusScope], a widget that manages a [FocusScopeNode] and provides
-///     access to scope information and actions to its descendant widgets.
-///   * [FocusAttachment], a widget that connects a [FocusScopeNode] to the
-///     focus tree.
-///   * [FocusManager], a singleton that manages the focus and distributes key
-///     events to focused nodes.
+///  * [Focus], a widget that manages a [FocusNode] and provides access to focus
+///    information and actions to its descendant widgets.
+///  * [FocusScope], a widget that manages a [FocusScopeNode] and provides
+///    access to scope information and actions to its descendant widgets.
+///  * [FocusAttachment], a widget that connects a [FocusScopeNode] to the focus
+///    tree.
+///  * [FocusManager], a singleton that manages the focus and distributes key
+///    events to focused nodes.
 class FocusScopeNode extends FocusNode {
   /// Creates a FocusScope node.
   ///

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

@@ -120,19 +120,19 @@ import 'inherited_notifier.dart';
 ///
 /// See also:
 ///
-///   * [FocusNode], which represents a node in the focus hierarchy and
-///     [FocusNode]'s API documentation includes a detailed explanation of its
-///     role in the overall focus system.
-///   * [FocusScope], a widget that manages a group of focusable widgets using a
-///     [FocusScopeNode].
-///   * [FocusScopeNode], a node that collects focus nodes into a group for
-///     traversal.
-///   * [FocusManager], a singleton that manages the primary focus and
-///     distributes key events to focused nodes.
-///   * [FocusTraversalPolicy], an object used to determine how to move the
-///     focus to other nodes.
-///   * [DefaultFocusTraversal], a widget used to configure the default focus
-///     traversal policy for a widget subtree.
+///  * [FocusNode], which represents a node in the focus hierarchy and
+///    [FocusNode]'s API documentation includes a detailed explanation of its role
+///    in the overall focus system.
+///  * [FocusScope], a widget that manages a group of focusable widgets using a
+///    [FocusScopeNode].
+///  * [FocusScopeNode], a node that collects focus nodes into a group for
+///    traversal.
+///  * [FocusManager], a singleton that manages the primary focus and
+///    distributes key events to focused nodes.
+///  * [FocusTraversalPolicy], an object used to determine how to move the focus
+///    to other nodes.
+///  * [DefaultFocusTraversal], a widget used to configure the default focus
+///    traversal policy for a widget subtree.
 class Focus extends StatefulWidget {
   /// Creates a widget that manages a [FocusNode].
   ///
@@ -247,10 +247,10 @@ class Focus extends StatefulWidget {
   ///
   /// See also:
   ///
-  ///   - [DefaultFocusTraversal], a widget that sets the traversal policy for
-  ///     its descendants.
-  ///   - [FocusTraversalPolicy], a class that can be extended to describe a
-  ///     traversal policy.
+  ///  * [DefaultFocusTraversal], a widget that sets the traversal policy for
+  ///    its descendants.
+  ///  * [FocusTraversalPolicy], a class that can be extended to describe a
+  ///    traversal policy.
   /// {@endtemplate}
   final bool canRequestFocus;
 
@@ -489,17 +489,17 @@ class _FocusState extends State<Focus> {
 ///
 /// See also:
 ///
-///   * [FocusScopeNode], which represents a scope node in the focus hierarchy.
-///   * [FocusNode], which represents a node in the focus hierarchy and has an
-///     explanation of the focus system.
-///   * [Focus], a widget that manages a [FocusNode] and allows easy access to
-///     managing focus without having to manage the node.
-///   * [FocusManager], a singleton that manages the focus and distributes key
-///     events to focused nodes.
-///   * [FocusTraversalPolicy], an object used to determine how to move the
-///     focus to other nodes.
-///   * [DefaultFocusTraversal], a widget used to configure the default focus
-///     traversal policy for a widget subtree.
+///  * [FocusScopeNode], which represents a scope node in the focus hierarchy.
+///  * [FocusNode], which represents a node in the focus hierarchy and has an
+///    explanation of the focus system.
+///  * [Focus], a widget that manages a [FocusNode] and allows easy access to
+///    managing focus without having to manage the node.
+///  * [FocusManager], a singleton that manages the focus and distributes key
+///    events to focused nodes.
+///  * [FocusTraversalPolicy], an object used to determine how to move the focus
+///    to other nodes.
+///  * [DefaultFocusTraversal], a widget used to configure the default focus
+///    traversal policy for a widget subtree.
 class FocusScope extends Focus {
   /// Creates a widget that manages a [FocusScopeNode].
   ///

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

@@ -53,16 +53,16 @@ enum TraversalDirection {
 ///
 /// See also:
 ///
-///   * [FocusNode], for a description of the focus system.
-///   * [DefaultFocusTraversal], a widget that imposes a traversal policy on the
-///     [Focus] nodes below it in the widget hierarchy.
-///   * [FocusNode], which is affected by the traversal policy.
-///   * [WidgetOrderFocusTraversalPolicy], a policy that relies on the widget
-///     creation order to describe the order of traversal.
-///   * [ReadingOrderTraversalPolicy], a policy that describes the order as the
-///     natural "reading order" for the current [Directionality].
-///   * [DirectionalFocusTraversalPolicyMixin] a mixin class that implements
-///     focus traversal in a direction.
+///  * [FocusNode], for a description of the focus system.
+///  * [DefaultFocusTraversal], a widget that imposes a traversal policy on the
+///    [Focus] nodes below it in the widget hierarchy.
+///  * [FocusNode], which is affected by the traversal policy.
+///  * [WidgetOrderFocusTraversalPolicy], a policy that relies on the widget
+///    creation order to describe the order of traversal.
+///  * [ReadingOrderTraversalPolicy], a policy that describes the order as the
+///    natural "reading order" for the current [Directionality].
+///  * [DirectionalFocusTraversalPolicyMixin] a mixin class that implements
+///    focus traversal in a direction.
 abstract class FocusTraversalPolicy {
   /// Returns the node that should receive focus if there is no current focus
   /// in the [FocusScopeNode] that [currentNode] belongs to.
@@ -191,13 +191,13 @@ class _DirectionalPolicyData {
 ///
 /// See also:
 ///
-///   * [FocusNode], for a description of the focus system.
-///   * [DefaultFocusTraversal], a widget that imposes a traversal policy on the
-///     [Focus] nodes below it in the widget hierarchy.
-///   * [WidgetOrderFocusTraversalPolicy], a policy that relies on the widget
-///     creation order to describe the order of traversal.
-///   * [ReadingOrderTraversalPolicy], a policy that describes the order as the
-///     natural "reading order" for the current [Directionality].
+///  * [FocusNode], for a description of the focus system.
+///  * [DefaultFocusTraversal], a widget that imposes a traversal policy on the
+///    [Focus] nodes below it in the widget hierarchy.
+///  * [WidgetOrderFocusTraversalPolicy], a policy that relies on the widget
+///    creation order to describe the order of traversal.
+///  * [ReadingOrderTraversalPolicy], a policy that describes the order as the
+///    natural "reading order" for the current [Directionality].
 mixin DirectionalFocusTraversalPolicyMixin on FocusTraversalPolicy {
   final Map<FocusScopeNode, _DirectionalPolicyData> _policyData = <FocusScopeNode, _DirectionalPolicyData>{};
 
@@ -559,13 +559,13 @@ mixin DirectionalFocusTraversalPolicyMixin on FocusTraversalPolicy {
 ///
 /// See also:
 ///
-///   * [FocusNode], for a description of the focus system.
-///   * [DefaultFocusTraversal], a widget that imposes a traversal policy on the
-///     [Focus] nodes below it in the widget hierarchy.
-///   * [ReadingOrderTraversalPolicy], a policy that describes the order as the
-///     natural "reading order" for the current [Directionality].
-///   * [DirectionalFocusTraversalPolicyMixin] a mixin class that implements
-///     focus traversal in a direction.
+///  * [FocusNode], for a description of the focus system.
+///  * [DefaultFocusTraversal], a widget that imposes a traversal policy on the
+///    [Focus] nodes below it in the widget hierarchy.
+///  * [ReadingOrderTraversalPolicy], a policy that describes the order as the
+///    natural "reading order" for the current [Directionality].
+///  * [DirectionalFocusTraversalPolicyMixin] a mixin class that implements
+///    focus traversal in a direction.
 class WidgetOrderFocusTraversalPolicy extends FocusTraversalPolicy with DirectionalFocusTraversalPolicyMixin {
   /// Creates a const [WidgetOrderFocusTraversalPolicy].
   WidgetOrderFocusTraversalPolicy();
@@ -687,13 +687,13 @@ class _SortData {
 ///
 /// See also:
 ///
-///   * [FocusNode], for a description of the focus system.
-///   * [DefaultFocusTraversal], a widget that imposes a traversal policy on the
-///     [Focus] nodes below it in the widget hierarchy.
-///   * [WidgetOrderFocusTraversalPolicy], a policy that relies on the widget
-///     creation order to describe the order of traversal.
-///   * [DirectionalFocusTraversalPolicyMixin] a mixin class that implements
-///     focus traversal in a direction.
+///  * [FocusNode], for a description of the focus system.
+///  * [DefaultFocusTraversal], a widget that imposes a traversal policy on the
+///    [Focus] nodes below it in the widget hierarchy.
+///  * [WidgetOrderFocusTraversalPolicy], a policy that relies on the widget
+///    creation order to describe the order of traversal.
+///  * [DirectionalFocusTraversalPolicyMixin] a mixin class that implements
+///    focus traversal in a direction.
 class ReadingOrderTraversalPolicy extends FocusTraversalPolicy with DirectionalFocusTraversalPolicyMixin {
   @override
   FocusNode findFirstFocus(FocusNode currentNode) {
@@ -829,13 +829,13 @@ class ReadingOrderTraversalPolicy extends FocusTraversalPolicy with DirectionalF
 ///
 /// See also:
 ///
-///   * [FocusNode], for a description of the focus system.
-///   * [WidgetOrderFocusTraversalPolicy], a policy that relies on the widget
-///     creation order to describe the order of traversal.
-///   * [ReadingOrderTraversalPolicy], a policy that describes the order as the
-///     natural "reading order" for the current [Directionality].
-///   * [DirectionalFocusTraversalPolicyMixin] a mixin class that implements
-///     focus traversal in a direction.
+///  * [FocusNode], for a description of the focus system.
+///  * [WidgetOrderFocusTraversalPolicy], a policy that relies on the widget
+///    creation order to describe the order of traversal.
+///  * [ReadingOrderTraversalPolicy], a policy that describes the order as the
+///    natural "reading order" for the current [Directionality].
+///  * [DirectionalFocusTraversalPolicyMixin] a mixin class that implements
+///    focus traversal in a direction.
 class DefaultFocusTraversal extends InheritedWidget {
   /// Creates a [DefaultFocusTraversal] object.
   ///

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

@@ -53,7 +53,11 @@ class UniqueKey extends LocalKey {
 /// Used to tie the identity of a widget to the identity of an object used to
 /// generate that widget.
 ///
-/// See also the discussions at [Key] and [Widget.key].
+/// See also:
+///
+///  * [Key], the base class for all keys.
+///  * The discussion at [Widget.key] for more information about how widgets use
+///    keys.
 class ObjectKey extends LocalKey {
   /// Creates a key that uses [identical] on [value] for its [operator==].
   const ObjectKey(this.value);
@@ -99,7 +103,10 @@ class ObjectKey extends LocalKey {
 /// You cannot simultaneously include two widgets in the tree with the same
 /// global key. Attempting to do so will assert at runtime.
 ///
-/// See also the discussion at [Widget.key].
+/// See also:
+///
+///  * The discussion at [Widget.key] for more information about how widgets use
+///    keys.
 @optionalTypeArgs
 abstract class GlobalKey<T extends State<StatefulWidget>> extends Key {
   /// Creates a [LabeledGlobalKey], which is a [GlobalKey] with a label used for
@@ -410,7 +417,9 @@ abstract class Widget extends DiagnosticableTree {
   /// Generally, a widget that is the only child of another widget does not need
   /// an explicit key.
   ///
-  /// See also the discussions at [Key] and [GlobalKey].
+  /// See also:
+  ///
+  ///  * The discussions at [Key] and [GlobalKey].
   final Key key;
 
   /// Inflates this configuration to a concrete instance.
@@ -1188,8 +1197,10 @@ abstract class State<T extends StatefulWidget> extends Diagnosticable {
   /// If you override this, make sure to end your method with a call to
   /// super.deactivate().
   ///
-  /// See also [dispose], which is called after [deactivate] if the widget is
-  /// removed from the tree permanently.
+  /// See also:
+  ///
+  ///  * [dispose], which is called after [deactivate] if the widget is removed
+  ///    from the tree permanently.
   @protected
   @mustCallSuper
   void deactivate() { }
@@ -1210,7 +1221,9 @@ abstract class State<T extends StatefulWidget> extends Diagnosticable {
   /// If you override this, make sure to end your method with a call to
   /// super.dispose().
   ///
-  /// See also [deactivate], which is called prior to [dispose].
+  /// See also:
+  ///
+  ///  * [deactivate], which is called prior to [dispose].
   @protected
   @mustCallSuper
   void dispose() {

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

@@ -30,6 +30,7 @@ typedef CreateRectTween = Tween<Rect> Function(Rect begin, Rect end);
 /// implicitly.
 ///
 /// See also:
+///
 ///  * [TransitionBuilder], which is similar but only takes a [BuildContext]
 ///    and a child widget.
 typedef HeroPlaceholderBuilder = Widget Function(

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

@@ -70,8 +70,8 @@ class IconThemeData extends Diagnosticable {
   ///
   /// See also:
   ///
-  /// * [CupertinoIconThemeData.resolve] an implementation that resolves
-  ///   [CupertinoIconThemeData.color] before returning.
+  ///  * [CupertinoIconThemeData.resolve] an implementation that resolves
+  ///    [CupertinoIconThemeData.color] before returning.
   IconThemeData resolve(BuildContext context) => this;
 
   /// Whether all the properties of this object are non-null.

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

@@ -77,9 +77,9 @@ enum Orientation {
 ///
 /// See also:
 ///
-/// * [Scaffold], [SafeArea], [CupertinoTabScaffold], and
-/// [CupertinoPageScaffold], all of which are informed by [padding],
-/// [viewPadding], and [viewInsets].
+///  * [Scaffold], [SafeArea], [CupertinoTabScaffold], and
+///    [CupertinoPageScaffold], all of which are informed by [padding],
+///    [viewPadding], and [viewInsets].
 @immutable
 class MediaQueryData {
   /// Creates data for a media query with explicit values.
@@ -174,8 +174,8 @@ class MediaQueryData {
   ///
   /// See also:
   ///
-  /// * [ui.window], which provides some additional detail about this property
-  ///   and how it relates to [padding] and [viewPadding].
+  ///  * [ui.window], which provides some additional detail about this property
+  ///    and how it relates to [padding] and [viewPadding].
   final EdgeInsets viewInsets;
 
   /// The parts of the display that are partially obscured by system UI,
@@ -213,8 +213,8 @@ class MediaQueryData {
   ///
   /// See also:
   ///
-  /// * [ui.window], which provides some additional detail about this
-  ///   property and how it relates to [padding] and [viewInsets].
+  ///  * [ui.window], which provides some additional detail about this
+  ///    property and how it relates to [padding] and [viewInsets].
   final EdgeInsets viewPadding;
 
   /// The areas along the edges of the display where the system consumes
@@ -739,7 +739,7 @@ class MediaQuery extends InheritedWidget {
   /// See also:
   ///
   ///  * [MediaQueryData.viewPadding], the affected property of the
-  ///  [MediaQueryData].
+  ///    [MediaQueryData].
   ///  * [removePadding], the same thing but for [MediaQueryData.padding].
   ///  * [removeViewInsets], the same thing but for [MediaQueryData.viewInsets].
   factory MediaQuery.removeViewPadding({

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

@@ -81,7 +81,9 @@ class AndroidView extends StatefulWidget {
   /// A [PlatformViewFactory](/javadoc/io/flutter/plugin/platform/PlatformViewFactory.html)
   /// for this type must have been registered.
   ///
-  /// See also: [AndroidView] for an example of registering a platform view factory.
+  /// See also:
+  ///
+  ///  * [AndroidView] for an example of registering a platform view factory.
   final String viewType;
 
   /// {@template flutter.widgets.platformViews.createdParam}
@@ -701,7 +703,9 @@ class _UiKitPlatformView extends LeafRenderObjectWidget {
 
 /// The parameters used to create a [PlatformViewController].
 ///
-/// See also [CreatePlatformViewCallback] which uses this object to create a [PlatformViewController].
+/// See also:
+///
+///  * [CreatePlatformViewCallback] which uses this object to create a [PlatformViewController].
 class PlatformViewCreationParams {
 
   const PlatformViewCreationParams._({
@@ -737,7 +741,8 @@ class PlatformViewCreationParams {
 /// The returned widget should present the platform view associated with `controller`.
 ///
 /// See also:
-/// * [PlatformViewSurface], a common widget for presenting platform views.
+///
+///  * [PlatformViewSurface], a common widget for presenting platform views.
 typedef PlatformViewSurfaceFactory = Widget Function(BuildContext context, PlatformViewController controller);
 
 /// Constructs a [PlatformViewController].
@@ -745,7 +750,9 @@ typedef PlatformViewSurfaceFactory = Widget Function(BuildContext context, Platf
 /// The [PlatformViewController.id] field of the created controller must match the value of the
 /// params [PlatformViewCreationParams.id] field.
 ///
-/// See also [PlatformViewLink.onCreate].
+/// See also:
+///
+///  * [PlatformViewLink], which links a platform view with the Flutter framework.
 typedef CreatePlatformViewCallback = PlatformViewController Function(PlatformViewCreationParams params);
 
 /// Links a platform view with the Flutter framework.
@@ -785,8 +792,9 @@ class PlatformViewLink extends StatefulWidget {
   /// The `surfaceFactory` and the `onCreatePlatformView` must not be null.
   ///
   /// See also:
-  /// * [PlatformViewSurface] for details on the widget returned by `surfaceFactory`.
-  /// * [PlatformViewCreationParams] for how each parameter can be used when implementing `createPlatformView`.
+  ///
+  ///  * [PlatformViewSurface] for details on the widget returned by `surfaceFactory`.
+  ///  * [PlatformViewCreationParams] for how each parameter can be used when implementing `createPlatformView`.
   const PlatformViewLink({
     Key key,
     @required PlatformViewSurfaceFactory surfaceFactory,
@@ -904,8 +912,9 @@ class _PlatformViewLinkState extends State<PlatformViewLink> {
 /// If the associated platform view is not created the [PlatformViewSurface] does not paint any contents.
 ///
 /// See also:
-/// * [AndroidView] which embeds an Android platform view in the widget hierarchy.
-/// * [UIKitView] which embeds an iOS platform view in the widget hierarchy.
+///
+///  * [AndroidView] which embeds an Android platform view in the widget hierarchy.
+///  * [UIKitView] which embeds an iOS platform view in the widget hierarchy.
 // TODO(amirh): Link to the embedder's system compositor documentation once available.
 class PlatformViewSurface extends LeafRenderObjectWidget {
 

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

@@ -24,8 +24,10 @@ class RouteNotificationMessages {
   ///
   /// There are three methods: 'routePushed', 'routePopped', 'routeReplaced'.
   ///
-  /// See also [SystemChannels.navigation], which handles subsequent navigation
-  /// requests.
+  /// See also:
+  ///
+  ///  * [SystemChannels.navigation], which handles subsequent navigation
+  ///    requests.
   static void _notifyRouteChange(String methodName, Route<dynamic> route, Route<dynamic> previousRoute) {
     final String previousRouteName = previousRoute?.settings?.name;
     final String routeName = route?.settings?.name;

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

@@ -526,8 +526,8 @@ abstract class ScrollPosition extends ViewportOffset with ScrollMetrics {
   ///
   /// See also:
   ///
-  /// * [ScrollPositionAlignmentPolicy] for the way in which `alignment` is
-  ///   applied, and the way the given `object` is aligned.
+  ///  * [ScrollPositionAlignmentPolicy] for the way in which `alignment` is
+  ///    applied, and the way the given `object` is aligned.
   Future<void> ensureVisible(
     RenderObject object, {
     double alignment = 0.0,

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

@@ -25,7 +25,7 @@ import 'inherited_notifier.dart';
 ///
 /// See also:
 ///
-///  - [ShortcutManager], which uses [LogicalKeySet] (a [KeySet] subclass) to
+///  * [ShortcutManager], which uses [LogicalKeySet] (a [KeySet] subclass) to
 ///    define its key map.
 class KeySet<T extends KeyboardKey> extends Diagnosticable {
   /// A constructor for making a [KeySet] of up to four keys.
@@ -231,9 +231,9 @@ class ShortcutManager extends ChangeNotifier with DiagnosticableMixin {
 ///
 /// See also:
 ///
-///   * [Intent], a class for containing a description of a user
-///     action to be invoked.
-///   * [Action], a class for defining an invocation of a user action.
+///  * [Intent], a class for containing a description of a user action to be
+///    invoked.
+///  * [Action], a class for defining an invocation of a user action.
 class Shortcuts extends StatefulWidget {
   /// Creates a ActionManager object.
   ///

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

@@ -13,7 +13,8 @@ import 'media_query.dart';
 // Examples can assume:
 // String _name;
 
-/// The text style to apply to descendant [Text] widgets without explicit style.
+/// The text style to apply to descendant [Text] widgets which don't have an
+/// explicit style.
 ///
 /// See also:
 ///

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

@@ -819,8 +819,9 @@ class _TextSelectionHandleOverlayState
 ///
 /// See also:
 ///
-/// * [TextField], which implements this delegate for the Material textfield.
-/// * [CupertinoTextField], which implements this delegate for the Cupertino textfield.
+///  * [TextField], which implements this delegate for the Material textfield.
+///  * [CupertinoTextField], which implements this delegate for the Cupertino
+///    textfield.
 abstract class TextSelectionGestureDetectorBuilderDelegate {
   /// [GlobalKey] to the [EditableText] for which the
   /// [TextSelectionGestureDetectorBuilder] will build a [TextSelectionGestureDetector].

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

@@ -691,7 +691,10 @@ class RelativePositionedTransition extends AnimatedWidget {
 
   /// The animation that controls the child's size and position.
   ///
-  /// See also [size].
+  /// See also:
+  ///
+  ///  * [size], which gets the size of the box that the [Positioned] widget's
+  ///    offsets are relative to.
   Animation<Rect> get rect => listenable as Animation<Rect>;
 
   /// The [Positioned] widget's offsets are relative to a box of this

packages/flutter/test/material/dropdown_form_field_test.dart

@@ -630,4 +630,4 @@ void main() {
     await tester.pumpAndSettle();
     expect(find.text('Two as an Arabic numeral: 2'), findsOneWidget);
   });
-}
+}
\ No newline at end of file

packages/flutter/test/rendering/mock_canvas.dart

@@ -122,7 +122,11 @@ abstract class PaintPattern {
   /// Calls are skipped until a call to [Canvas.save] is found. If none is
   /// found, the matcher fails.
   ///
-  /// See also: [restore], [saveRestore].
+  /// See also:
+  ///
+  ///  * [restore], which indicates that a restore is expected next.
+  ///  * [saveRestore], which indicates that a matching pair of save/restore
+  ///    calls is expected next.
   void save();
 
   /// Indicates that a restore is expected next.
@@ -130,7 +134,11 @@ abstract class PaintPattern {
   /// Calls are skipped until a call to [Canvas.restore] is found. If none is
   /// found, the matcher fails.
   ///
-  /// See also: [save], [saveRestore].
+  /// See also:
+  ///
+  ///  * [save], which indicates that a save is expected next.
+  ///  * [saveRestore], which indicates that a matching pair of save/restore
+  ///    calls is expected next.
   void restore();
 
   /// Indicates that a matching pair of save/restore calls is expected next.
@@ -139,7 +147,10 @@ abstract class PaintPattern {
   /// skipped until the matching [Canvas.restore] call is found. If no matching
   /// pair of calls could be found, the matcher fails.
   ///
-  /// See also: [save], [restore].
+  /// See also:
+  ///
+  ///  * [save], which indicates that a save is expected next.
+  ///  * [restore], which indicates that a restore is expected next.
   void saveRestore();
 
   /// Indicates that a rectangular clip is expected next.

packages/flutter/test/widgets/semantics_tester.dart

@@ -197,8 +197,10 @@ class TestSemantics {
   /// The test screen's size in physical pixels, typically used as the [rect]
   /// for the node with id zero.
   ///
-  /// See also [new TestSemantics.root], which uses this value to describe the
-  /// root node.
+  /// See also:
+  ///
+  ///  * [new TestSemantics.root], which uses this value to describe the root
+  ///    node.
   static const Rect rootRect = Rect.fromLTWH(0.0, 0.0, 2400.0, 1800.0);
 
   /// The test screen's size in logical pixels, useful for the [rect] of