Various documentation improvements (#12855)

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

@@ -30,8 +30,10 @@ final TextStyle _kBackgroundButtonTextStyle = _kButtonTextStyle.copyWith(
 );
 
 const EdgeInsets _kButtonPadding = const EdgeInsets.all(16.0);
-const EdgeInsets _kBackgroundButtonPadding =
-    const EdgeInsets.symmetric(vertical: 16.0, horizontal: 64.0);
+const EdgeInsets _kBackgroundButtonPadding = const EdgeInsets.symmetric(
+  vertical: 16.0,
+  horizontal: 64.0,
+);
 
 /// An iOS-style button.
 ///
@@ -199,22 +201,22 @@ class _CupertinoButtonState extends State<CupertinoButton> with SingleTickerProv
         button: true,
         child: new ConstrainedBox(
           constraints: widget.minSize == null
-          ? const BoxConstraints()
-          : new BoxConstraints(
-            minWidth: widget.minSize,
-            minHeight: widget.minSize,
-          ),
+            ? const BoxConstraints()
+            : new BoxConstraints(
+              minWidth: widget.minSize,
+              minHeight: widget.minSize,
+            ),
           child: new FadeTransition(
             opacity: _opacityTween.animate(new CurvedAnimation(
-                parent: _animationController,
-                curve: Curves.decelerate,
+              parent: _animationController,
+              curve: Curves.decelerate,
             )),
             child: new DecoratedBox(
               decoration: new BoxDecoration(
                 borderRadius: widget.borderRadius,
                 color: backgroundColor != null && !enabled
-                ? _kDisabledBackground
-                : backgroundColor,
+                  ? _kDisabledBackground
+                  : backgroundColor,
               ),
               child: new Padding(
                 padding: widget.padding ?? (backgroundColor != null
@@ -225,10 +227,10 @@ class _CupertinoButtonState extends State<CupertinoButton> with SingleTickerProv
                   heightFactor: 1.0,
                   child: new DefaultTextStyle(
                     style: backgroundColor != null
-                    ? _kBackgroundButtonTextStyle
-                    : enabled
-                    ? _kButtonTextStyle
-                    : _kDisabledButtonTextStyle,
+                      ? _kBackgroundButtonTextStyle
+                      : enabled
+                        ? _kButtonTextStyle
+                        : _kDisabledButtonTextStyle,
                     child: widget.child,
                   ),
                 ),

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

@@ -132,7 +132,7 @@ class MaterialApp extends StatefulWidget {
   /// This value is passed unmodified to [WidgetsApp.title].
   final String title;
 
-  /// If non-null this function is called to produce the app's
+  /// If non-null this callback is called to produce the app's
   /// title string, otherwise [title] is used.
   ///
   /// The [onGenerateTitle] `context` parameter includes the [WidgetsApp]'s
@@ -141,6 +141,9 @@ class MaterialApp extends StatefulWidget {
   ///
   /// This callback function must not return null.
   ///
+  /// The [onGenerateTitle] callback is called each time the [MaterialApp]
+  /// rebuilds.
+  ///
   /// This value is passed unmodified to [WidgetsApp.onGenerateTitle].
   final GenerateAppTitle onGenerateTitle;
 

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

@@ -9,18 +9,18 @@ import 'colors.dart';
 import 'list_tile.dart';
 import 'material.dart';
 
-/// The alginment of a [Drawer] which is used to identify positioning
-/// of the [Drawer]
-///
+/// The possible alignments of a [Drawer].
 enum DrawerAlignment {
-  /// Denotes that the [Drawer] is at the start side of the [Scaffold]
-  /// i.e. left side when Directionality is LTR
-  /// and right side when Directionality is RTL
+  /// Denotes that the [Drawer] is at the start side of the [Scaffold].
+  ///
+  /// This corresponds to the left side when the text direction is left-to-right
+  /// and the right side when the text direction is right-to-left.
   start,
 
-  /// Denotes that the [Drawer] is at the end side of the [Scaffold]
-  /// i.e. right side when Directionality is LTR
-  /// and left side when Directionality is RTL
+  /// Denotes that the [Drawer] is at the end side of the [Scaffold].
+  ///
+  /// This corresponds to the right side when the text direction is left-to-right
+  /// and the left side when the text direction is right-to-left.
   end,
 }
 
@@ -122,8 +122,8 @@ class Drawer extends StatelessWidget {
 ///
 /// See also:
 ///
-///  * [Drawer]
-///  * [Scaffold.drawer]
+///  * [Drawer], a container with the default width of a drawer.
+///  * [Scaffold.drawer], the [Scaffold] slot for showing a drawer.
 class DrawerController extends StatefulWidget {
   /// Creates a controller for a [Drawer].
   ///
@@ -143,9 +143,10 @@ class DrawerController extends StatefulWidget {
   /// Typically a [Drawer].
   final Widget child;
 
-  /// The alginment of a [Drawer] which is used to identify positioning
-  /// of the [Drawer] i.e. either start-side or end-side
+  /// The alignment of the [Drawer].
   ///
+  /// This controls the direction in which the user should swipe to open and
+  /// close the drawer.
   final DrawerAlignment alignment;
 
   @override

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

@@ -15,11 +15,11 @@ import 'system_channels.dart';
 ///
 /// See also:
 ///
-///  * [RawKeyEventDataAndroid]
- //  * [RawKeyEventDataFuchsia]
-///  * [RawKeyEvent]
-///  * [RawKeyDownEvent]
-///  * [RawKeyUpEvent]
+///  * [RawKeyEventDataAndroid], a specialization for Android.
+///  * [RawKeyEventDataFuchsia], a specialization for Fuchsia.
+///  * [RawKeyDownEvent] and [RawKeyUpEvent], the classes that hold the
+///    reference to [RawKeyEventData] subclasses.
+///  * [RawKeyboard], which uses these interfaces to expose key data.
 @immutable
 abstract class RawKeyEventData {
   /// Abstract const constructor. This constructor enables subclasses to provide
@@ -31,6 +31,10 @@ abstract class RawKeyEventData {
 ///
 /// This object contains information about key events obtained from Android's
 /// `KeyEvent` interface.
+///
+/// See also:
+///
+///  * [RawKeyboard], which uses this interface to expose key data.
 class RawKeyEventDataAndroid extends RawKeyEventData {
   /// Creates a key event data structure specific for Android.
   ///
@@ -68,6 +72,10 @@ class RawKeyEventDataAndroid extends RawKeyEventData {
 ///
 /// This object contains information about key events obtained from Fuchsia's
 /// `KeyData` interface.
+///
+/// See also:
+///
+///  * [RawKeyboard], which uses this interface to expose key data.
 class RawKeyEventDataFuchsia extends RawKeyEventData {
   /// Creates a key event data structure specific for Android.
   ///
@@ -105,8 +113,9 @@ class RawKeyEventDataFuchsia extends RawKeyEventData {
 ///
 /// See also:
 ///
-///  * [RawKeyDownEvent]
-///  * [RawKeyUpEvent]
+///  * [RawKeyDownEvent], a specialization for events representing the user pressing a key.
+///  * [RawKeyUpEvent], a specialization for events representing the user releasing a key.
+///  * [RawKeyboard], which uses this interface to expose key data.
 ///  * [RawKeyboardListener], a widget that listens for raw key events.
 @immutable
 abstract class RawKeyEvent {
@@ -115,11 +124,55 @@ abstract class RawKeyEvent {
     @required this.data,
   });
 
+  /// Creates a concrete [RawKeyEvent] class from a message in the form received
+  /// on the [SystemChannels.keyEvent] channel.
+  factory RawKeyEvent.fromMessage(Map<String, dynamic> message) {
+    RawKeyEventData data;
+
+    final String keymap = message['keymap'];
+    switch (keymap) {
+      case 'android':
+        data = new RawKeyEventDataAndroid(
+          flags: message['flags'] ?? 0,
+          codePoint: message['codePoint'] ?? 0,
+          keyCode: message['keyCode'] ?? 0,
+          scanCode: message['scanCode'] ?? 0,
+          metaState: message['metaState'] ?? 0,
+        );
+        break;
+      case 'fuchsia':
+        data = new RawKeyEventDataFuchsia(
+          hidUsage: message['hidUsage'] ?? 0,
+          codePoint: message['codePoint'] ?? 0,
+          modifiers: message['modifiers'] ?? 0,
+        );
+        break;
+      default:
+        // We don't yet implement raw key events on iOS, but we don't hit this
+        // exception because the engine never sends us these messages.
+        throw new FlutterError('Unknown keymap for key events: $keymap');
+    }
+
+    final String type = message['type'];
+    switch (type) {
+      case 'keydown':
+        return new RawKeyDownEvent(data: data);
+      case 'keyup':
+        return new RawKeyUpEvent(data: data);
+      default:
+        throw new FlutterError('Unknown key event type: $type');
+    }
+  }
+
   /// Platform-specific information about the key event.
   final RawKeyEventData data;
 }
 
 /// The user has pressed a key on the keyboard.
+///
+/// See also:
+///
+///  * [RawKeyboard], which uses this interface to expose key data.
 class RawKeyDownEvent extends RawKeyEvent {
   /// Creates a key event that represents the user pressing a key.
   const RawKeyDownEvent({
@@ -128,6 +181,10 @@ class RawKeyDownEvent extends RawKeyEvent {
 }
 
 /// The user has released a key on the keyboard.
+///
+/// See also:
+///
+///  * [RawKeyboard], which uses this interface to expose key data.
 class RawKeyUpEvent extends RawKeyEvent {
   /// Creates a key event that represents the user releasing a key.
   const RawKeyUpEvent({
@@ -135,44 +192,6 @@ class RawKeyUpEvent extends RawKeyEvent {
   }) : super(data: data);
 }
 
-RawKeyEvent _toRawKeyEvent(Map<String, dynamic> message) {
-  RawKeyEventData data;
-
-  final String keymap = message['keymap'];
-  switch (keymap) {
-    case 'android':
-      data = new RawKeyEventDataAndroid(
-        flags: message['flags'] ?? 0,
-        codePoint: message['codePoint'] ?? 0,
-        keyCode: message['keyCode'] ?? 0,
-        scanCode: message['scanCode'] ?? 0,
-        metaState: message['metaState'] ?? 0,
-      );
-      break;
-    case 'fuchsia':
-      data = new RawKeyEventDataFuchsia(
-        hidUsage: message['hidUsage'] ?? 0,
-        codePoint: message['codePoint'] ?? 0,
-        modifiers: message['modifiers'] ?? 0,
-      );
-      break;
-    default:
-      // We don't yet implement raw key events on iOS, but we don't hit this
-      // exception because the engine never sends us these messages.
-      throw new FlutterError('Unknown keymap for key events: $keymap');
-  }
-
-  final String type = message['type'];
-  switch (type) {
-    case 'keydown':
-      return new RawKeyDownEvent(data: data);
-    case 'keyup':
-      return new RawKeyUpEvent(data: data);
-    default:
-      throw new FlutterError('Unknown key event type: $type');
-  }
-}
-
 /// An interface for listening to raw key events.
 ///
 /// Raw key events pass through as much information as possible from the
@@ -185,9 +204,11 @@ RawKeyEvent _toRawKeyEvent(Map<String, dynamic> message) {
 ///
 /// See also:
 ///
-///  * [RawKeyEvent]
-///  * [RawKeyDownEvent]
-///  * [RawKeyUpEvent]
+///  * [RawKeyDownEvent] and [RawKeyUpEvent], the classes used to describe
+///    specific raw key events.
+///  * [RawKeyboardListener], a widget that listens for raw key events.
+///  * [SystemChannels.keyEvent], the low-level channel used for receiving
+///    events from the system.
 class RawKeyboard {
   RawKeyboard._() {
     SystemChannels.keyEvent.setMessageHandler(_handleKeyEvent);
@@ -215,7 +236,7 @@ class RawKeyboard {
   Future<dynamic> _handleKeyEvent(dynamic message) async {
     if (_listeners.isEmpty)
       return;
-    final RawKeyEvent event = _toRawKeyEvent(message);
+    final RawKeyEvent event = new RawKeyEvent.fromMessage(message);
     if (event == null)
       return;
     for (ValueChanged<RawKeyEvent> listener in new List<ValueChanged<RawKeyEvent>>.from(_listeners))

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

@@ -106,7 +106,8 @@ class SystemChrome {
   /// be displayed in.
   ///
   /// The `orientation` argument is a list of [DeviceOrientation] enum values.
-  /// The empty list is synonymous with having all options enabled.
+  /// The empty list causes the application to defer to the operating system
+  /// default.
   static Future<Null> setPreferredOrientations(List<DeviceOrientation> orientations) async {
     await SystemChannels.platform.invokeMethod(
       'SystemChrome.setPreferredOrientations',

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

@@ -117,6 +117,9 @@ class WidgetsApp extends StatefulWidget {
   /// localized title.
   ///
   /// This callback function must not return null.
+  ///
+  /// The [onGenerateTitle] callback is called each time the [WidgetsApp]
+  /// rebuilds.
   final GenerateAppTitle onGenerateTitle;
 
   /// The default text style for [Text] in the application.

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

@@ -84,6 +84,9 @@ abstract class WidgetsBindingObserver {
   /// box, and false otherwise. The [WidgetsApp] widget uses this
   /// mechanism to notify the [Navigator] widget that it should pop
   /// its current route if possible.
+  ///
+  /// This method exposes the `popRoute` notification from
+  /// [SystemChannels.navigation].
   Future<bool> didPopRoute() => new Future<bool>.value(false);
 
   /// Called when the host tells the app to push a new route onto the
@@ -92,11 +95,16 @@ abstract class WidgetsBindingObserver {
   /// Observers are expected to return true if they were able to
   /// handle the notification. Observers are notified in registration
   /// order until one returns true.
+  ///
+  /// This method exposes the `pushRoute` notification from
+  /// [SystemChannels.navigation].
   Future<bool> didPushRoute(String route) => new Future<bool>.value(false);
 
   /// Called when the application's dimensions change. For example,
   /// when a phone is rotated.
   ///
+  /// This method exposes notifications from [Window.onMetricsChanged].
+  ///
   /// ## Sample code
   ///
   /// This [StatefulWidget] implements the parts of the [State] and
@@ -154,6 +162,8 @@ abstract class WidgetsBindingObserver {
   /// preferences, and it should affect all of the text sizes in the
   /// application.
   ///
+  /// This method exposes notifications from [Window.onTextScaleFactorChanged].
+  ///
   /// ## Sample code
   ///
   /// ```dart
@@ -200,6 +210,8 @@ abstract class WidgetsBindingObserver {
   /// Called when the system tells the app that the user's locale has
   /// changed. For example, if the user changes the system language
   /// settings.
+  ///
+  /// This method exposes notifications from [Window.onLocaleChanged].
   void didChangeLocale(Locale locale) { }
 
   /// Called when the system puts the app in the background or returns
@@ -207,9 +219,14 @@ abstract class WidgetsBindingObserver {
   ///
   /// An example of implementing this method is provided in the class-level
   /// documentation for the [WidgetsBindingObserver] class.
+  ///
+  /// This method exposes notifications from [SystemChannels.lifecycle].
   void didChangeAppLifecycleState(AppLifecycleState state) { }
 
   /// Called when the system is running low on memory.
+  ///
+  /// This method exposes the `memoryPressure` notification from
+  /// [SystemChannels.system].
   void didHaveMemoryPressure() { }
 }
 
@@ -359,6 +376,9 @@ abstract class WidgetsBinding extends BindingBase with GestureBinding, RendererB
   /// Notify all the observers that the locale has changed (using
   /// [WidgetsBindingObserver.didChangeLocale]), giving them the
   /// `locale` argument.
+  ///
+  /// This is called by [handleLocaleChanged] when the [Window.onLocaleChanged]
+  /// notification is received.
   void dispatchLocaleChanged(Locale locale) {
     for (WidgetsBindingObserver observer in _observers)
       observer.didChangeLocale(locale);
@@ -367,14 +387,17 @@ abstract class WidgetsBinding extends BindingBase with GestureBinding, RendererB
   /// Called when the system pops the current route.
   ///
   /// This first notifies the binding observers (using
-  /// [WidgetsBindingObserver.didPopRoute]), in registration order,
-  /// until one returns true, meaning that it was able to handle the
-  /// request (e.g. by closing a dialog box). If none return true,
-  /// then the application is shut down.
+  /// [WidgetsBindingObserver.didPopRoute]), in registration order, until one
+  /// returns true, meaning that it was able to handle the request (e.g. by
+  /// closing a dialog box). If none return true, then the application is shut
+  /// down by calling [SystemNavigator.pop].
   ///
   /// [WidgetsApp] uses this in conjunction with a [Navigator] to
   /// cause the back button to close dialog boxes, return from modal
   /// pages, and so forth.
+  ///
+  /// This method exposes the `popRoute` notification from
+  /// [SystemChannels.navigation].
   Future<Null> handlePopRoute() async {
     for (WidgetsBindingObserver observer in new List<WidgetsBindingObserver>.from(_observers)) {
       if (await observer.didPopRoute())
@@ -385,6 +408,14 @@ abstract class WidgetsBinding extends BindingBase with GestureBinding, RendererB
 
   /// Called when the host tells the app to push a new route onto the
   /// navigator.
+  ///
+  /// This notifies the binding observers (using
+  /// [WidgetsBindingObserver.didPushRoute]), in registration order, until one
+  /// returns true, meaning that it was able to handle the request (e.g. by
+  /// opening a dialog box). If none return true, then nothing happens.
+  ///
+  /// This method exposes the `pushRoute` notification from
+  /// [SystemChannels.navigation].
   Future<Null> handlePushRoute(String route) async {
     for (WidgetsBindingObserver observer in new List<WidgetsBindingObserver>.from(_observers)) {
       if (await observer.didPushRoute(route))
@@ -406,6 +437,8 @@ abstract class WidgetsBinding extends BindingBase with GestureBinding, RendererB
   ///
   /// Notifies all the observers using
   /// [WidgetsBindingObserver.didChangeAppLifecycleState].
+  ///
+  /// This method exposes notifications from [SystemChannels.lifecycle].
   void handleAppLifecycleStateChanged(AppLifecycleState state) {
     for (WidgetsBindingObserver observer in _observers)
       observer.didChangeAppLifecycleState(state);
@@ -429,11 +462,25 @@ abstract class WidgetsBinding extends BindingBase with GestureBinding, RendererB
     return null;
   }
 
+  /// Called when the operating system notifies the application of a memory
+  /// pressure situation.
+  ///
+  /// Notifies all the observers using
+  /// [WidgetsBindingObserver.didHaveMemoryPressure].
+  ///
+  /// This method exposes the `memoryPressure` notification from
+  /// [SystemChannels.system].
+  void handleMemoryPressure() {
+    for (WidgetsBindingObserver observer in _observers)
+      observer.didHaveMemoryPressure();
+  }
+
   Future<dynamic> _handleSystemMessage(Map<String, dynamic> message) async {
     final String type = message['type'];
-    if (type == 'memoryPressure') {
-      for (WidgetsBindingObserver observer in _observers)
-        observer.didHaveMemoryPressure();
+    switch (type) {
+      case 'memoryPressure':
+        handleMemoryPressure();
+        break;
     }
     return null;
   }