Tabs code/doc cleanup (#32654)

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

@@ -115,11 +115,10 @@ class TabController extends ChangeNotifier {
   /// Creates a new [TabController] with `index`, `previousIndex`, and `length`
   /// if they are non-null.
   ///
-  /// This will reuse the existing [_animationController].
+  /// This method is used by [DefaultTabController].
   ///
-  /// This is useful for [DefaultTabController], for example when
-  /// [DefaultTabController.length] is updated, this method is called so that a
-  /// new [TabController] is created without having to create a new [AnimationController].
+  /// When [DefaultTabController.length] is updated, this method is called to
+  /// create a new [TabController] without creating a new [AnimationController].
   TabController _copyWith({ int index, int length, int previousIndex }) {
     return TabController._(
       index: index ?? _index,
@@ -138,7 +137,7 @@ class TabController extends ChangeNotifier {
   /// animation's value can be [offset] by +/- 1.0 to reflect [TabBarView]
   /// drag scrolling.
   ///
-  /// If the TabController was disposed then return null.
+  /// If this [TabController] was disposed, then return null.
   Animation<double> get animation => _animationController?.view;
   AnimationController _animationController;
 
@@ -174,9 +173,10 @@ class TabController extends ChangeNotifier {
     }
   }
 
-  /// The index of the currently selected tab. Changing the index also updates
-  /// [previousIndex], sets the [animation]'s value to index, resets
-  /// [indexIsChanging] to false, and notifies listeners.
+  /// The index of the currently selected tab.
+  ///
+  /// Changing the index also updates [previousIndex], sets the [animation]'s
+  /// value to index, resets [indexIsChanging] to false, and notifies listeners.
   ///
   /// To change the currently selected tab and play the [animation] use [animateTo].
   ///
@@ -188,7 +188,9 @@ class TabController extends ChangeNotifier {
     _changeIndex(value);
   }
 
-  /// The index of the previously selected tab. Initially the same as [index].
+  /// The index of the previously selected tab.
+  ///
+  /// Initially the same as [index].
   int get previousIndex => _previousIndex;
   int _previousIndex;
 
@@ -210,8 +212,9 @@ class TabController extends ChangeNotifier {
     _changeIndex(value, duration: duration, curve: curve);
   }
 
-  /// The difference between the [animation]'s value and [index]. The offset
-  /// value must be between -1.0 and 1.0.
+  /// The difference between the [animation]'s value and [index].
+  ///
+  /// The offset value must be between -1.0 and 1.0.
   ///
   /// This property is typically set by the [TabBarView] when the user
   /// drags left or right. A value between -1.0 and 0.0 implies that the
@@ -313,8 +316,10 @@ class DefaultTabController extends StatefulWidget {
        assert(initialIndex >= 0 && initialIndex < length),
        super(key: key);
 
-  /// The total number of tabs. Typically greater than one. Must match
-  /// [TabBar.tabs]'s and [TabBarView.children]'s length.
+  /// The total number of tabs.
+  ///
+  /// Typically greater than one. Must match [TabBar.tabs]'s and
+  /// [TabBarView.children]'s length.
   final int length;
 
   /// The initial index of the selected tab.

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

@@ -45,8 +45,10 @@ enum TabBarIndicatorSize {
   label,
 }
 
-/// A material design [TabBar] tab. If both [icon] and [text] are
-/// provided, the text is displayed below the icon.
+/// A material design [TabBar] tab.
+///
+/// If both [icon] and [text] are provided, the text is displayed below
+/// the icon.
 ///
 /// See also:
 ///
@@ -55,9 +57,10 @@ enum TabBarIndicatorSize {
 ///  * [TabController], which coordinates tab selection between a [TabBar] and a [TabBarView].
 ///  * <https://material.io/design/components/tabs.html>
 class Tab extends StatelessWidget {
-  /// Creates a material design [TabBar] tab. At least one of [text], [icon],
-  /// and [child] must be non-null. The [text] and [child] arguments must not be
-  /// used at the same time.
+  /// Creates a material design [TabBar] tab.
+  ///
+  /// At least one of [text], [icon], and [child] must be non-null. The [text]
+  /// and [child] arguments must not be used at the same time.
   const Tab({
     Key key,
     this.text,
@@ -444,6 +447,18 @@ class _ChangeAnimation extends Animation<double> with AnimationWithParentMixin<d
   @override
   Animation<double> get parent => controller.animation;
 
+  @override
+  void removeStatusListener(AnimationStatusListener listener) {
+    if (parent != null)
+      super.removeStatusListener(listener);
+  }
+
+  @override
+  void removeListener(VoidCallback listener) {
+    if (parent != null)
+      super.removeListener(listener);
+  }
+
   @override
   double get value => _indexChangeProgress(controller);
 }
@@ -459,13 +474,13 @@ class _DragAnimation extends Animation<double> with AnimationWithParentMixin<dou
 
   @override
   void removeStatusListener(AnimationStatusListener listener) {
-    if (controller.animation != null)
+    if (parent != null)
       super.removeStatusListener(listener);
   }
 
   @override
   void removeListener(VoidCallback listener) {
-    if (controller.animation != null)
+    if (parent != null)
       super.removeListener(listener);
   }
 
@@ -607,26 +622,29 @@ class TabBar extends StatefulWidget implements PreferredSizeWidget {
 
   /// Whether this tab bar can be scrolled horizontally.
   ///
-  /// If [isScrollable] is true then each tab is as wide as needed for its label
+  /// If [isScrollable] is true, then each tab is as wide as needed for its label
   /// and the entire [TabBar] is scrollable. Otherwise each tab gets an equal
   /// share of the available space.
   final bool isScrollable;
 
-  /// The color of the line that appears below the selected tab. If this parameter
-  /// is null then the value of the Theme's indicatorColor property is used.
+  /// The color of the line that appears below the selected tab.
+  ///
+  /// If this parameter is null, then the value of the Theme's indicatorColor
+  /// property is used.
   ///
   /// If [indicator] is specified, this property is ignored.
   final Color indicatorColor;
 
-  /// The thickness of the line that appears below the selected tab. The value
-  /// of this parameter must be greater than zero.
+  /// The thickness of the line that appears below the selected tab.
   ///
-  /// The default value of [indicatorWeight] is 2.0.
+  /// The value of this parameter must be greater than zero and its default
+  /// value is 2.0.
   ///
   /// If [indicator] is specified, this property is ignored.
   final double indicatorWeight;
 
   /// The horizontal padding for the line that appears below the selected tab.
+  ///
   /// For [isScrollable] tab bars, specifying [kTabLabelPadding] will align
   /// the indicator with the tab's text for [Tab] widgets and all but the
   /// shortest [Tab.text] values.
@@ -650,7 +668,7 @@ class TabBar extends StatefulWidget implements PreferredSizeWidget {
   /// The indicator's size is based on the tab's bounds. If [indicatorSize]
   /// is [TabBarIndicatorSize.tab] the tab's bounds are as wide as the space
   /// occupied by the tab in the tab bar. If [indicatorSize] is
-  /// [TabBarIndicatorSize.label] then the tab's bounds are only as wide as
+  /// [TabBarIndicatorSize.label], then the tab's bounds are only as wide as
   /// the tab widget itself.
   final Decoration indicator;
 
@@ -671,33 +689,34 @@ class TabBar extends StatefulWidget implements PreferredSizeWidget {
   /// Unselected tab labels are rendered with the same color rendered at 70%
   /// opacity unless [unselectedLabelColor] is non-null.
   ///
-  /// If this parameter is null then the color of the [ThemeData.primaryTextTheme]'s
+  /// If this parameter is null, then the color of the [ThemeData.primaryTextTheme]'s
   /// body2 text color is used.
   final Color labelColor;
 
   /// The color of unselected tab labels.
   ///
-  /// If this property is null, Unselected tab labels are rendered with the
-  /// [labelColor] rendered at 70% opacity.
+  /// If this property is null, unselected tab labels are rendered with the
+  /// [labelColor] with 70% opacity.
   final Color unselectedLabelColor;
 
-  /// The text style of the selected tab labels. If [unselectedLabelStyle] is
-  /// null then this text style will be used for both selected and unselected
-  /// label styles.
+  /// The text style of the selected tab labels.
   ///
-  /// If this property is null then the text style of the [ThemeData.primaryTextTheme]'s
-  /// body2 definition is used.
+  /// If [unselectedLabelStyle] is null, then this text style will be used for
+  /// both selected and unselected label styles.
+  ///
+  /// If this property is null, then the text style of the
+  /// [ThemeData.primaryTextTheme]'s body2 definition is used.
   final TextStyle labelStyle;
 
   /// The padding added to each of the tab labels.
   ///
-  /// If this property is null then kTabLabelPadding is used.
+  /// If this property is null, then kTabLabelPadding is used.
   final EdgeInsetsGeometry labelPadding;
 
   /// The text style of the unselected tab labels
   ///
-  /// If this property is null then the [labelStyle] value is used. If [labelStyle]
-  /// is null then the text style of the [ThemeData.primaryTextTheme]'s
+  /// If this property is null, then the [labelStyle] value is used. If [labelStyle]
+  /// is null, then the text style of the [ThemeData.primaryTextTheme]'s
   /// body2 definition is used.
   final TextStyle unselectedLabelStyle;
 
@@ -1031,7 +1050,7 @@ class _TabBarState extends State<TabBar> {
       }
     }
 
-    // Add the tap handler to each tab. If the tab bar is not scrollable
+    // Add the tap handler to each tab. If the tab bar is not scrollable,
     // then give all of the tabs equal flexibility so that they each occupy
     // the same share of the tab bar's overall width.
     final int tabCount = widget.tabs.length;
@@ -1086,7 +1105,9 @@ class _TabBarState extends State<TabBar> {
 }
 
 /// A page view that displays the widget which corresponds to the currently
-/// selected tab. Typically used in conjunction with a [TabBar].
+/// selected tab.
+///
+/// This widget is typically used in conjunction with a [TabBar].
 ///
 /// If a [TabController] is not provided, then there must be a [DefaultTabController]
 /// ancestor.
@@ -1353,11 +1374,13 @@ class TabPageSelectorIndicator extends StatelessWidget {
   }
 }
 
-/// Displays a row of small circular indicators, one per tab. The selected
-/// tab's indicator is highlighted. Often used in conjunction with a [TabBarView].
+/// Displays a row of small circular indicators, one per tab.
 ///
-/// If a [TabController] is not provided, then there must be a [DefaultTabController]
-/// ancestor.
+/// The selected tab's indicator is highlighted. Often used in conjunction with
+/// a [TabBarView].
+///
+/// If a [TabController] is not provided, then there must be a
+/// [DefaultTabController] ancestor.
 class TabPageSelector extends StatelessWidget {
   /// Creates a compact widget that indicates which tab has been selected.
   const TabPageSelector({
@@ -1371,8 +1394,8 @@ class TabPageSelector extends StatelessWidget {
 
   /// This widget's selection and animation state.
   ///
-  /// If [TabController] is not provided, then the value of [DefaultTabController.of]
-  /// will be used.
+  /// If [TabController] is not provided, then the value of
+  /// [DefaultTabController.of] will be used.
   final TabController controller;
 
   /// The indicator circle's diameter (the default value is 12.0).
@@ -1380,13 +1403,13 @@ class TabPageSelector extends StatelessWidget {
 
   /// The indicator circle's fill color for unselected pages.
   ///
-  /// If this parameter is null then the indicator is filled with [Colors.transparent].
+  /// If this parameter is null, then the indicator is filled with [Colors.transparent].
   final Color color;
 
   /// The indicator circle's fill color for selected pages and border color
   /// for all indicator circles.
   ///
-  /// If this parameter is null then the indicator is filled with the theme's
+  /// If this parameter is null, then the indicator is filled with the theme's
   /// accent color, [ThemeData.accentColor].
   final Color selectedColor;