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/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(

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,7 +229,9 @@ 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
+/// See also:
+///
+///  * [FlutterErrorDetailsForPointerRouter], which is also used by the
 ///    gesture library.
 class FlutterErrorDetailsForPointerEventDispatcher extends FlutterErrorDetails {
   /// Creates a [FlutterErrorDetailsForPointerEventDispatcher] object with the given

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,7 +123,9 @@ class PointerRouter {
 /// Variant of [FlutterErrorDetails] with extra fields for the gestures
 /// library's pointer router ([PointerRouter]).
 ///
-/// See also [FlutterErrorDetailsForPointerEventDispatcher], which is also used
+/// See also:
+///
+///  * [FlutterErrorDetailsForPointerEventDispatcher], which is also used
 ///    by the gestures library.
 class FlutterErrorDetailsForPointerRouter extends FlutterErrorDetails {
   /// Creates a [FlutterErrorDetailsForPointerRouter] object with the given

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_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/inline_span.dart

@@ -40,6 +40,7 @@ typedef InlineSpanVisitor = bool Function(InlineSpan span);
 /// For [PlaceholderSpan]s, [InlineSpanSemanticsInformation.placeholder] is used by default.
 ///
 /// See also:
+///
 ///  * [InlineSpan.getSemanticsInformation]
 @immutable
 class InlineSpanSemanticsInformation {

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,7 +273,9 @@ 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
+  /// 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));
@@ -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/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/system_channels.dart

@@ -22,12 +22,6 @@ 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.
   ///
@@ -41,6 +35,9 @@ class SystemChannels {
   ///
   /// 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,6 +380,7 @@ class SystemChrome {
   /// {@end-tool}
   ///
   /// See also:
+  ///
   ///  * [AnnotatedRegion], the widget used to place data into the layer tree.
   static void setSystemUIOverlayStyle(SystemUiOverlayStyle style) {
     assert(style != 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].

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,7 +84,9 @@ 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
+  /// See also:
+  ///
+  ///  * [layoutDirection], which controls the interpretation of values in
   ///    [location].
   final TextDirection textDirection;
 
@@ -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/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,7 +96,9 @@ 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
+/// 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;

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/focus_manager.dart

@@ -417,9 +417,9 @@ class FocusNode with DiagnosticableTreeMixin, ChangeNotifier {
   ///
   /// See also:
   ///
-  ///   - [DefaultFocusTraversal], a widget that sets the traversal policy for
+  ///  * [DefaultFocusTraversal], a widget that sets the traversal policy for
   ///    its descendants.
-  ///   - [FocusTraversalPolicy], a class that can be extended to describe a
+  ///  * [FocusTraversalPolicy], a class that can be extended to describe a
   ///    traversal policy.
   bool get canRequestFocus {
     final FocusScopeNode scope = enclosingScope;
@@ -942,12 +942,12 @@ 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.
+///  * [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.
+///  * [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 {

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

@@ -121,16 +121,16 @@ 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.
+///    [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.
+///  * [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 {
@@ -247,9 +247,9 @@ class Focus extends StatefulWidget {
   ///
   /// See also:
   ///
-  ///   - [DefaultFocusTraversal], a widget that sets the traversal policy for
+  ///  * [DefaultFocusTraversal], a widget that sets the traversal policy for
   ///    its descendants.
-  ///   - [FocusTraversalPolicy], a class that can be extended to describe a
+  ///  * [FocusTraversalPolicy], a class that can be extended to describe a
   ///    traversal policy.
   /// {@endtemplate}
   final bool canRequestFocus;
@@ -496,8 +496,8 @@ class _FocusState extends State<Focus> {
 ///    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.
+///  * [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 {

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/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,6 +741,7 @@ class PlatformViewCreationParams {
 /// The returned widget should present the platform view associated with `controller`.
 ///
 /// See also:
+///
 ///  * [PlatformViewSurface], a common widget for presenting platform views.
 typedef PlatformViewSurfaceFactory = Widget Function(BuildContext context, PlatformViewController controller);
 
@@ -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,6 +792,7 @@ 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`.
   const PlatformViewLink({
@@ -904,6 +912,7 @@ 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.
 // TODO(amirh): Link to the embedder's system compositor documentation once available.

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

@@ -24,7 +24,9 @@ class RouteNotificationMessages {
   ///
   /// There are three methods: 'routePushed', 'routePopped', 'routeReplaced'.
   ///
-  /// See also [SystemChannels.navigation], which handles subsequent navigation
+  /// 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;

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,8 +231,8 @@ class ShortcutManager extends ChangeNotifier with DiagnosticableMixin {
 ///
 /// See also:
 ///
-///   * [Intent], a class for containing a description of a user
-///     action to be invoked.
+///  * [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

@@ -820,7 +820,8 @@ class _TextSelectionHandleOverlayState
 /// See also:
 ///
 ///  * [TextField], which implements this delegate for the Material textfield.
-/// * [CupertinoTextField], which implements this delegate for the Cupertino 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/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