Add some more dartdocs (#8259)

packages/flutter/lib/src/animation/animation_controller.dart

@@ -179,6 +179,10 @@ class AnimationController extends Animation<double>
     _checkStatusChanged();
   }
 
+  /// The rate of change of [value] per second.
+  ///
+  /// If [isAnimating] is false, then [value] is not changing and the rate of
+  /// change is zero.
   double get velocity {
     if (!isAnimating)
       return 0.0;

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

@@ -255,8 +255,22 @@ class AppBar extends StatefulWidget {
   /// Defaults to being adapted to the current [TargetPlatform].
   final bool centerTitle;
 
+  /// How opaque the toolbar part of the app bar is.
+  ///
+  /// A value of 1.0 is fully opaque, and a value of 0.0 is fully transparent.
+  ///
+  /// Typically, this value is not changed from its default value (1.0). It is
+  /// used by [SliverAppBar] to animate the opacity of the toolbar when the app
+  /// bar is scrolled.
   final double toolbarOpacity;
 
+  /// How opaque the bottom part of the app bar is.
+  ///
+  /// A value of 1.0 is fully opaque, and a value of 0.0 is fully transparent.
+  ///
+  /// Typically, this value is not changed from its default value (1.0). It is
+  /// used by [SliverAppBar] to animate the opacity of the toolbar when the app
+  /// bar is scrolled.
   final double bottomOpacity;
 
   final double _bottomHeight;
@@ -286,10 +300,10 @@ class AppBar extends StatefulWidget {
   }
 
   @override
-  AppBarState createState() => new AppBarState();
+  _AppBarState createState() => new _AppBarState();
 }
 
-class AppBarState extends State<AppBar> {
+class _AppBarState extends State<AppBar> {
   bool _hasDrawer = false;
   bool _canPop = false;
 
@@ -562,6 +576,35 @@ class _SliverAppBarDelegate extends SliverPersistentHeaderDelegate {
   }
 }
 
+/// A material design app bar that integrates with a [CustomScrollView].
+///
+/// An app bar consists of a toolbar and potentially other widgets, such as a
+/// [TabBar] and a [FlexibleSpaceBar]. App bars typically expose one or more
+/// common actions with [IconButton]s which are optionally followed by a
+/// [PopupMenuButton] for less common operations.
+///
+/// Sliver app bars are typically used as the first child of a
+/// [CustomScrollView], which lets the app bar integrate with the scroll view so
+/// that it can vary in height according to the scroll offset or float above the
+/// other content in the scroll view. For a fixed-height app bar at the top of
+/// the screen see [AppBar], which is used in the [Scaffold.appBar] slot.
+///
+/// The AppBar displays the toolbar widgets, [leading], [title], and
+/// [actions], above the [bottom] (if any). If a [flexibleSpace] widget is
+/// specified then it is stacked behind the toolbar and the bottom widget.
+///
+/// See also:
+///
+///  * [CustomScrollView], which integrates the [SliverAppBar] into its
+///    scrolling.
+///  * [AppBar], which is a fixed-height app bar for use in [Scaffold.appBar].
+///  * [TabBar], which is typically placed in the [bottom] slot of the [AppBar]
+///    if the screen has multiple pages arranged in tabs.
+///  * [IconButton], which is used with [actions] to show buttons on the app bar.
+///  * [PopupMenuButton], to show a popup menu on the app bar, via [actions].
+///  * [FlexibleSpaceBar], which is used with [flexibleSpace] when the app bar
+///    can expand and collapse.
+///  * <https://material.google.com/layout/structure.html#structure-toolbars>
 class SliverAppBar extends StatelessWidget {
   /// Creates a material design app bar that can be placed in a [CustomScrollView].
   SliverAppBar({
@@ -585,6 +628,7 @@ class SliverAppBar extends StatelessWidget {
     assert(primary != null);
     assert(floating != null);
     assert(pinned != null);
+    assert(!floating || !pinned);
   }
 
   /// A widget to display before the [title].
@@ -702,8 +746,17 @@ class SliverAppBar extends StatelessWidget {
   /// See also [AppBar.getExpandedHeightFor].
   final double expandedHeight;
 
+  /// Whether the app bar should become visible as soon as the user scrolls
+  /// towards the app bar.
+  ///
+  /// Otherwise, the user will need to scroll near the top of the scroll view to
+  /// reveal the app bar.
   final bool floating;
 
+  /// Whether the app bar should remain visible at the start of the scroll view.
+  ///
+  /// The app bar can still expand an contract as the user scrolls, but it will
+  /// remain visible rather than being scrolled out of view.
   final bool pinned;
 
   @override

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

@@ -52,6 +52,10 @@ class FlexibleSpaceBar extends StatefulWidget {
   /// Defaults to being adapted to the current [TargetPlatform].
   final bool centerTitle;
 
+  /// Wraps a widget that contains an [AppBar] to convey sizing information down
+  /// to the [FlexibleSpaceBar].
+  ///
+  /// Used by [Scaffold] and [SliverAppBar].
   static Widget createSettings({
     double toolbarOpacity,
     double minExtent,

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

@@ -357,6 +357,10 @@ abstract class InkFeature {
     assert(referenceBox != null);
   }
 
+  /// The [MaterialInkController] associated with this [InkFeature].
+  ///
+  /// Typically used by subclasses to call
+  /// [MaterialInkController.markNeedsPaint] when they need to repaint.
   MaterialInkController get controller => _controller;
   _RenderInkFeatures _controller;
 

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

@@ -492,6 +492,7 @@ class ScaffoldState extends State<Scaffold> with TickerProviderStateMixin {
 
   final GlobalKey<DrawerControllerState> _drawerKey = new GlobalKey<DrawerControllerState>();
 
+  /// Whether this scaffold has a non-null [Scaffold.drawer].
   bool get hasDrawer => config.drawer != null;
 
   /// Opens the [Drawer] (if any).

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

@@ -10,15 +10,32 @@ import 'package:flutter/widgets.dart';
 
 import 'theme.dart';
 
+/// A material design scrollbar.
+///
+/// A scrollbar indicates which portion of a [Scrollable] widget is actually
+/// visible.
+///
+/// To add a scrollbar to a [ScrollView], simply wrap the scroll view widget in
+/// a [Scrollbar] widget.
+///
+/// See also:
+///
+///  * [ListView], which display a linear, scrollable list of children.
+///  * [GridView], which display a 2 dimensional, scrollable array of children.
 class Scrollbar extends StatefulWidget {
+  /// Creates a material design scrollbar that wraps the given [child].
+  ///
+  /// The [child] should be a source of [ScrollNotification] notifications,
+  /// typically a [Scrollable] widget.
   Scrollbar({
     Key key,
-    this.child,
+    @required this.child,
   }) : super(key: key);
 
-  /// The subtree to place inside the [Scrollbar]. This should include
-  /// a source of [ScrollNotification] notifications, typically a [Scrollable]
-  /// widget.
+  /// The subtree to place inside the [Scrollbar].
+  ///
+  /// This should include a source of [ScrollNotification] notifications,
+  /// typically a [Scrollable] widget.
   final Widget child;
 
   @override

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

@@ -82,8 +82,8 @@ class TabController extends ChangeNotifier {
   /// selected tab is changed, the animation's value equals [index]. The
   /// animation's value can be [offset] by +/- 1.0 to reflect [TabBarView]
   /// drag scrolling.
-  final AnimationController _animationController;
   Animation<double> get animation => _animationController.view;
+  final AnimationController _animationController;
 
   /// The total number of tabs. Must be greater than one.
   final int length;
@@ -217,6 +217,9 @@ class _TabControllerScope extends InheritedWidget {
 /// }
 /// ```
 class DefaultTabController extends StatefulWidget {
+  /// Creates a default tab controller for the given [child] widget.
+  ///
+  /// The [length] argument must be great than one.
   DefaultTabController({
     Key key,
     @required this.length,

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

@@ -312,14 +312,27 @@ class _ChangeAnimation extends Animation<double> with AnimationWithParentMixin<d
   double get value => _indexChangeProgress(controller);
 }
 
-/// A material design widget that displays a horizontal row of tabs. Typically
-/// created as part of an [AppBar] and in conjuction with a [TabBarView].
+/// A material design widget that displays a horizontal row of tabs.
 ///
-/// If a [TabController] is not provided, then there must be a [DefaultTabController]
-/// ancestor.
+/// Typically created as part of an [AppBar] and in conjuction with a
+/// [TabBarView].
+///
+/// If a [TabController] is not provided, then there must be a
+/// [DefaultTabController] ancestor.
+///
+/// Requires one of its ancestors to be a [Material] widget.
 ///
-/// Requires one of its ancestors to be a [Material] widget
+/// See also:
+///
+///  * [TabBarView], which displays the contents that the tab bar is selecting
+///    between.
 class TabBar extends StatefulWidget implements AppBarBottomWidget {
+  /// Creates a material design tab bar.
+  ///
+  /// The [tabs] argument must not be nuull and must have more than one widget.
+  ///
+  /// If a [TabController] is not provided, then there must be a
+  /// [DefaultTabController] ancestor.
   TabBar({
     Key key,
     @required this.tabs,

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

@@ -112,6 +112,7 @@ class TextPainter {
   }
 
   /// An optional maximum number of lines for the text to span, wrapping if necessary.
+  ///
   /// If the text exceeds the given number of lines, it will be truncated according
   /// to [overflow].
   ///
@@ -127,6 +128,12 @@ class TextPainter {
   }
 
   ui.Paragraph _layoutTemplate;
+
+  /// The height of a zero-width space in [style] in logical pixels.
+  ///
+  /// Not every line of text in [style] will have this height, but this height
+  /// is "typical" for text in [style] and useful for sizing other objects
+  /// relative a typical line of text.
   double get preferredLineHeight {
     assert(text != null);
     if (_layoutTemplate == null) {
@@ -206,6 +213,10 @@ class TextPainter {
     return null;
   }
 
+  /// Whether the previous call to [layout] attempted to produce more than
+  /// [maxLines] lines.
+  ///
+  /// If [didExceedMaxLines] is true, then any overflow effect is operative.
   bool get didExceedMaxLines {
     assert(!_needsLayout);
     return _paragraph.didExceedMaxLines;

packages/flutter/lib/src/physics/simulation.dart

@@ -30,6 +30,7 @@ import 'tolerance.dart';
 /// should establish a convention and use that convention consistently with all
 /// related objects.
 abstract class Simulation {
+  /// Initializes the [tolerance] field for subclasses.
   Simulation({ this.tolerance: Tolerance.defaultTolerance });
 
   /// The position of the object in the simulation at the given time.

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

@@ -143,6 +143,8 @@ abstract class RendererBinding extends BindingBase implements SchedulerBinding,
     setSemanticsEnabled(ui.window.semanticsEnabled);
   }
 
+  /// Whether the render tree associated with this binding should produce a tree
+  /// of [SemanticsNode] objects.
   void setSemanticsEnabled(bool enabled) {
     if (enabled) {
       _semanticsHandle ??= _pipelineOwner.ensureSemantics();

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

@@ -9,8 +9,9 @@ import 'object.dart';
 
 const double _kMaxWidth = 100000.0;
 const double _kMaxHeight = 100000.0;
+
 // Line length to fit small phones without dynamically checking size.
-const String line = '\n────────────────────\n\n';
+const String _kLine = '\n\n────────────────────\n\n';
 
 /// A render object used as a placeholder when an error occurs.
 ///
@@ -45,8 +46,8 @@ class RenderErrorBox extends RenderBox {
         ui.ParagraphBuilder builder = new ui.ParagraphBuilder(paragraphStyle);
         builder.pushStyle(textStyle);
         builder.addText(
-          '$message$line$message$line$message$line$message$line$message$line$message$line'
-          '$message$line$message$line$message$line$message$line$message$line$message'
+          '$message$_kLine$message$_kLine$message$_kLine$message$_kLine$message$_kLine$message$_kLine'
+          '$message$_kLine$message$_kLine$message$_kLine$message$_kLine$message$_kLine$message'
         );
         _paragraph = builder.build();
       }