Improve Tabs documentation (#31502)

Added info regarding matching lengths requirement and included links to sample implementation

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

@@ -71,13 +71,15 @@ import 'constants.dart';
 /// ```
 /// {@end-tool}
 class TabController extends ChangeNotifier {
-  /// Creates an object that manages the state required by [TabBar] and a [TabBarView].
+  /// Creates an object that manages the state required by [TabBar] and a
+  /// [TabBarView].
   ///
-  /// The [length] must not be null or negative. Typically its a value greater than one, i.e.
-  /// typically there are two or more tabs.
+  /// The [length] must not be null or negative. Typically its a value greater
+  /// than one, i.e. typically there are two or more tabs. The [length] must
+  /// match [TabBar.tabs]'s and [TabBarView.children]'s length.
   ///
-  /// The `initialIndex` must be valid given [length] and must not be null. If [length] is
-  /// zero, then `initialIndex` must be 0 (the default).
+  /// The `initialIndex` must be valid given [length] and must not be null. If
+  /// [length] is zero, then `initialIndex` must be 0 (the default).
   TabController({ int initialIndex = 0, @required this.length, @required TickerProvider vsync })
     : assert(length != null && length >= 0),
       assert(initialIndex != null && initialIndex >= 0 && (length == 0 || initialIndex < length)),
@@ -103,7 +105,8 @@ class TabController extends ChangeNotifier {
   Animation<double> get animation => _animationController?.view ?? kAlwaysCompleteAnimation;
   final AnimationController _animationController;
 
-  /// The total number of tabs. Typically greater than one.
+  /// The total number of tabs. Typically greater than one. Must match
+  /// [TabBar.tabs]'s and [TabBarView.children]'s length.
   final int length;
 
   void _changeIndex(int value, { Duration duration, Curve curve }) {
@@ -249,7 +252,8 @@ class _TabControllerScope extends InheritedWidget {
 class DefaultTabController extends StatefulWidget {
   /// Creates a default tab controller for the given [child] widget.
   ///
-  /// The [length] argument is typically greater than one.
+  /// The [length] argument is typically greater than one. The [length] must
+  /// match [TabBar.tabs]'s and [TabBarView.children]'s length.
   ///
   /// The [initialIndex] argument must not be null.
   const DefaultTabController({
@@ -260,7 +264,8 @@ class DefaultTabController extends StatefulWidget {
   }) : assert(initialIndex != null),
        super(key: key);
 
-  /// The total number of tabs. Typically greater than one.
+  /// 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

@@ -530,12 +530,15 @@ class _TabBarScrollController extends ScrollController {
 ///
 /// If a [TabController] is not provided, then a [DefaultTabController] ancestor
 /// must be provided instead. The tab controller's [TabController.length] must
-/// equal the length of the [tabs] list.
+/// equal the length of the [tabs] list and the length of the
+/// [TabBarView.children] list.
 ///
 /// Requires one of its ancestors to be a [Material] widget.
 ///
 /// Uses values from [TabBarTheme] if it is set in the current context.
 ///
+/// To see a sample implementation, visit the [TabController] documentation.
+///
 /// See also:
 ///
 ///  * [TabBarView], which displays page views that correspond to each tab.
@@ -580,7 +583,8 @@ class TabBar extends StatefulWidget implements PreferredSizeWidget {
 
   /// Typically a list of two or more [Tab] widgets.
   ///
-  /// The length of this list must match the [controller]'s [TabController.length].
+  /// The length of this list must match the [controller]'s [TabController.length]
+  /// and the length of the [TabBarView.children] list.
   final List<Widget> tabs;
 
   /// This widget's selection and animation state.
@@ -1069,6 +1073,11 @@ class _TabBarState extends State<TabBar> {
 ///
 /// If a [TabController] is not provided, then there must be a [DefaultTabController]
 /// ancestor.
+///
+/// The tab controller's [TabController.length] must equal the length of the
+/// [children] list and the length of the [TabBar.tabs] list.
+///
+/// To see a sample implementation, visit the [TabController] documentation.
 class TabBarView extends StatefulWidget {
   /// Creates a page view with one child per tab.
   ///
@@ -1089,7 +1098,8 @@ class TabBarView extends StatefulWidget {
   /// will be used.
   final TabController controller;
 
-  /// One widget per tab.
+  /// One widget per tab. Its length must match the length of the [TabBar.tabs]
+  /// list, as well as the [controller]'s [TabController.length].
   final List<Widget> children;
 
   /// How the page view should respond to user input.