Add more docs around .of functions (#6482)

examples/flutter_gallery/lib/demo/persistent_bottom_sheet_demo.dart

@@ -59,7 +59,7 @@ class _PersistentBottomSheetDemoState extends State<PersistentBottomSheetDemo> {
         content: new Text('You tapped the floating action button.'),
         actions: <Widget>[
           new FlatButton(
-            onPressed: () { Navigator.of(context).pop(); },
+            onPressed: () { Navigator.pop(context); },
             child: new Text('OK')
           )
         ]

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

@@ -93,6 +93,12 @@ class ButtonTheme extends InheritedWidget {
   final EdgeInsets padding;
 
   /// The color from the closest instance of this class that encloses the given context.
+  ///
+  /// Typical usage is as follows:
+  ///
+  /// ```dart
+  /// ButtonTheme theme = ButtonTheme.of(context);
+  /// ```
   static ButtonTheme of(BuildContext context) {
     ButtonTheme result = context.inheritFromWidgetOfExactType(ButtonTheme);
     return result ?? const ButtonTheme();

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

@@ -49,6 +49,12 @@ class IconTheme extends InheritedWidget {
   /// context.
   ///
   /// Defaults to the current [ThemeData.iconTheme].
+  ///
+  /// Typical usage is as follows:
+  ///
+  /// ```dart
+  /// IconThemeData theme = IconTheme.of(context);
+  /// ```
   static IconThemeData of(BuildContext context) {
     IconTheme result = context.inheritFromWidgetOfExactType(IconTheme);
     return result?.data ?? Theme.of(context).iconTheme;

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

@@ -203,6 +203,12 @@ class Material extends StatefulWidget {
 
   /// The ink controller from the closest instance of this class that
   /// encloses the given context.
+  ///
+  /// Typical usage is as follows:
+  ///
+  /// ```dart
+  /// MaterialInkController inkController = Material.of(context);
+  /// ```
   static MaterialInkController of(BuildContext context) {
     final _RenderInkFeatures result = context.ancestorRenderObjectOfType(const TypeMatcher<_RenderInkFeatures>());
     return result;

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

@@ -376,6 +376,55 @@ class Scaffold extends StatefulWidget {
   final bool resizeToAvoidBottomPadding;
 
   /// The state from the closest instance of this class that encloses the given context.
+  ///
+  /// Typical usage is as follows:
+  ///
+  /// ```dart
+  /// @override
+  /// Widget build(BuildContext context) {
+  ///   return new RaisedButton(
+  ///     child: new Text('SHOW A SNACKBAR'),
+  ///     onPressed: () {
+  ///       Scaffold.of(context).showSnackBar(new SnackBar(
+  ///         content: new Text('Hello!'),
+  ///       ));
+  ///     },
+  ///   );
+  /// }
+  /// ```
+  ///
+  /// When the [Scaffold] is actually created in the same `build` function, the
+  /// `context` argument to the `build` function can't be used to find the
+  /// [Scaffold] (since it's "above" the widget being returned). In such cases,
+  /// the following technique with a [Builder] can be used to provide a new
+  /// scope with a [BuildContext] that is "under" the [Scaffold]:
+  ///
+  /// ```dart
+  /// @override
+  /// Widget build(BuildContext context) {
+  ///   return new Scaffold(
+  ///     appBar: new AppBar(
+  ///       title: new Text('Demo')
+  ///     ),
+  ///     body: new Builder(
+  ///       // Create an inner BuildContext so that the onPressed methods
+  ///       // can refer to the Scaffold with Scaffold.of().
+  ///       builder: (BuildContext context) {
+  ///         return new Center(
+  ///           child: new RaisedButton(
+  ///             child: new Text('SHOW A SNACKBAR'),
+  ///             onPressed: () {
+  ///               Scaffold.of(context).showSnackBar(new SnackBar(
+  ///                 content: new Text('Hello!'),
+  ///               ));
+  ///             },
+  ///           ),
+  ///         );
+  ///       },
+  ///     ),
+  ///   );
+  /// }
+  /// ```
   static ScaffoldState of(BuildContext context) => context.ancestorStateOfType(const TypeMatcher<ScaffoldState>());
 
   @override

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

@@ -507,6 +507,12 @@ class TabBarSelection<T> extends StatefulWidget {
   TabBarSelectionState<T> createState() => new TabBarSelectionState<T>();
 
   /// The state from the closest instance of this class that encloses the given context.
+  ///
+  /// Typical usage is as follows:
+  ///
+  /// ```dart
+  /// TabBarSelectionState<Foo> tabState = TabBarSelection.of/*<Foo>*/(context);
+  /// ```
   static TabBarSelectionState<dynamic/*=T*/> of/*<T>*/(BuildContext context) {
     return context.ancestorStateOfType(new TypeMatcher<TabBarSelectionState<dynamic/*=T*/>>());
   }

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

@@ -59,6 +59,46 @@ class Theme extends InheritedWidget {
   /// situations where its useful to wrap a route's widgets with a Theme, but only
   /// when the app's theme is being shadowed by a theme widget that is farather
   /// down in the tree. See [isMaterialAppTheme].
+  ///
+  /// Typical usage is as follows:
+  ///
+  /// ```dart
+  /// @override
+  /// Widget build(BuildContext context) {
+  ///   return new Text(
+  ///     'Example',
+  ///     style: Theme.of(context).textTheme.title,
+  ///   );
+  /// }
+  /// ```
+  ///
+  /// When the [Theme] is actually created in the same `build` function
+  /// (possibly indirectly, e.g. as part of a [MaterialApp]), the `context`
+  /// argument to the `build` function can't be used to find the [Theme] (since
+  /// it's "above" the widget being returned). In such cases, the following
+  /// technique with a [Builder] can be used to provide a new scope with a
+  /// [BuildContext] that is "under" the [Theme]:
+  ///
+  /// ```dart
+  /// @override
+  /// Widget build(BuildContext context) {
+  ///   return new MaterialApp(
+  ///     theme: new ThemeData.light(),
+  ///     body: new Builder(
+  ///       // Create an inner BuildContext so that we can refer to
+  ///       // the Theme with Theme.of().
+  ///       builder: (BuildContext context) {
+  ///         return new Center(
+  ///           child: new Text(
+  ///             'Example',
+  ///             style: Theme.of(context).textTheme.title,
+  ///           ),
+  ///         );
+  ///       },
+  ///     ),
+  ///   );
+  /// }
+  /// ```
   static ThemeData of(BuildContext context, { bool shadowThemeOnly: false }) {
     final Theme theme = context.inheritFromWidgetOfExactType(Theme);
     final ThemeData themeData = theme?.data ?? _kFallbackTheme;

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

@@ -2392,6 +2392,12 @@ class DefaultAssetBundle extends InheritedWidget {
   ///
   /// If there is no [DefaultAssetBundle] ancestor widget in the tree
   /// at the given context, then this will return the [rootBundle].
+  ///
+  /// Typical usage is as follows:
+  ///
+  /// ```dart
+  /// AssetBundle bundle = DefaultAssetBundle.of(context);
+  /// ```
   static AssetBundle of(BuildContext context) {
     DefaultAssetBundle result = context.inheritFromWidgetOfExactType(DefaultAssetBundle);
     return result?.bundle ?? rootBundle;

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

@@ -103,6 +103,12 @@ class ClampOverscrolls extends InheritedWidget {
   }
 
   /// The closest instance of this class that encloses the given context.
+  ///
+  /// Typical usage is as follows:
+  ///
+  /// ```dart
+  /// ScrollableEdge edge = ClampOverscrolls.of(context).edge;
+  /// ```
   static ClampOverscrolls of(BuildContext context) {
     return context.inheritFromWidgetOfExactType(ClampOverscrolls);
   }

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

@@ -98,6 +98,12 @@ class FormScope extends InheritedWidget {
   Form get form => _formState.config;
 
   /// The closest [FormScope] encloses the given context.
+  ///
+  /// Typical usage is as follows:
+  ///
+  /// ```dart
+  /// FormScope form = FormScope.of(context);
+  /// ```
   static FormScope of(BuildContext context) {
     return context.inheritFromWidgetOfExactType(FormScope);
   }

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

@@ -24,6 +24,12 @@ class LocaleQuery extends InheritedWidget {
   final LocaleQueryData data;
 
   /// The data from the closest instance of this class that encloses the given context.
+  ///
+  /// Typical usage is as follows:
+  ///
+  /// ```dart
+  /// MyLocaleData data = LocaleQueryData.of(context);
+  /// ```
   static LocaleQueryData of(BuildContext context) {
     LocaleQuery query = context.inheritFromWidgetOfExactType(LocaleQuery);
     return query?.data;

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

@@ -124,6 +124,12 @@ class MediaQuery extends InheritedWidget {
   /// You can use this function to query the size an orientation of the screen.
   /// When that information changes, your widget will be scheduled to be rebuilt,
   /// keeping your widget up-to-date.
+  ///
+  /// Typical usage is as follows:
+  ///
+  /// ```dart
+  /// MediaQueryData media = MediaQuery.of(context);
+  /// ```
   static MediaQueryData of(BuildContext context) {
     MediaQuery query = context.inheritFromWidgetOfExactType(MediaQuery);
     return query?.data ?? new MediaQueryData.fromWindow(ui.window);

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

@@ -274,6 +274,12 @@ class Navigator extends StatefulWidget {
   /// callback. The returned route will be pushed into the navigator.
   ///
   /// Returns a Future that completes when the pushed route is popped.
+  ///
+  /// Typical usage is as follows:
+  ///
+  /// ```dart
+  /// Navigator.pushNamed(context, '/nyc/1776');
+  /// ```
   static Future<dynamic> pushNamed(BuildContext context, String routeName) {
     return Navigator.of(context).pushNamed(routeName);
   }
@@ -305,6 +311,12 @@ class Navigator extends StatefulWidget {
   ///
   /// Returns true if a route was popped; returns false if there are no further
   /// previous routes.
+  ///
+  /// Typical usage is as follows:
+  ///
+  /// ```dart
+  /// Navigator.pop(context);
+  /// ```
   static bool pop(BuildContext context, [ dynamic result ]) {
     return Navigator.of(context).pop(result);
   }
@@ -337,6 +349,12 @@ class Navigator extends StatefulWidget {
   /// the class of the current route. (In practice, this is usually "dynamic".)
   ///
   /// Returns a Future that completes when the pushed route is popped.
+  ///
+  /// Typical usage is as follows:
+  ///
+  /// ```dart
+  /// Navigator.popAndPushNamed(context, '/nyc/1776');
+  /// ```
   static Future<dynamic> popAndPushNamed(BuildContext context, String routeName, { dynamic result }) {
     NavigatorState navigator = Navigator.of(context);
     navigator.pop(result);
@@ -344,6 +362,15 @@ class Navigator extends StatefulWidget {
   }
 
   /// The state from the closest instance of this class that encloses the given context.
+  ///
+  /// Typical usage is as follows:
+  ///
+  /// ```dart
+  /// Navigator.of(context)
+  ///   ..pop()
+  ///   ..pop()
+  ///   ..pushNamed('/settings');
+  /// ```
   static NavigatorState of(BuildContext context) {
     NavigatorState navigator = context.ancestorStateOfType(const TypeMatcher<NavigatorState>());
     assert(() {

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

@@ -218,6 +218,12 @@ class Overlay extends StatefulWidget {
   /// if not. The exception attempts to explain that the calling [Widget] (the
   /// one given by the [debugRequiredFor] argument) needs an [Overlay] to be
   /// present to function.
+  ///
+  /// Typical usage is as follows:
+  ///
+  /// ```dart
+  /// OverlayState overlay = Overlay.of(context);
+  /// ```
   static OverlayState of(BuildContext context, { Widget debugRequiredFor }) {
     OverlayState result = context.ancestorStateOfType(const TypeMatcher<OverlayState>());
     assert(() {

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

@@ -121,6 +121,12 @@ class PageStorage extends StatelessWidget {
   /// The bucket from the closest instance of this class that encloses the given context.
   ///
   /// Returns `null` if none exists.
+  ///
+  /// Typical usage is as follows:
+  ///
+  /// ```dart
+  /// PageStorageBucket bucket = PageStorage.of(context);
+  /// ```
   static PageStorageBucket of(BuildContext context) {
     PageStorage widget = context.ancestorWidgetOfExactType(PageStorage);
     return widget?.bucket;

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

@@ -468,6 +468,12 @@ abstract class ModalRoute<T> extends TransitionRoute<T> with LocalHistoryRoute<T
   /// Returns the modal route most closely associated with the given context.
   ///
   /// Returns `null` if the given context is not associated with a modal route.
+  ///
+  /// Typical usage is as follows:
+  ///
+  /// ```dart
+  /// ModalRoute<dynamic> route = ModalRoute.of(context);
+  /// ```
   static ModalRoute<dynamic> of(BuildContext context) {
     _ModalScopeStatus widget = context.inheritFromWidgetOfExactType(_ModalScopeStatus);
     return widget?.route;

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

@@ -80,6 +80,12 @@ class ScrollConfiguration extends InheritedWidget {
   /// [ScrollConfigurationDelegate] that approximates the scrolling physics of
   /// the current platform (see [defaultTargetPlatform]) using a
   /// [OverscrollWhenScrollableBehavior] behavior model.
+  ///
+  /// Typical usage is as follows:
+  ///
+  /// ```dart
+  /// ScrollConfigurationDelegate scrollConfiguration = ScrollConfiguration.of(context);
+  /// ```
   static ScrollConfigurationDelegate of(BuildContext context) {
     ScrollConfiguration configuration = context.inheritFromWidgetOfExactType(ScrollConfiguration);
     return configuration?.delegate ?? _defaultDelegate;

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

@@ -155,6 +155,12 @@ class Scrollable extends StatefulWidget {
   final ScrollBuilder builder;
 
   /// The state from the closest instance of this class that encloses the given context.
+  ///
+  /// Typical usage is as follows:
+  ///
+  /// ```dart
+  /// ScrollableState scrollable = Scrollable.of(context);
+  /// ```
   static ScrollableState of(BuildContext context) {
     return context.ancestorStateOfType(const TypeMatcher<ScrollableState>());
   }

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

@@ -83,6 +83,12 @@ class DefaultTextStyle extends InheritedWidget {
   ///
   /// If no such instance exists, returns an instance created by
   /// [DefaultTextStyle.fallback], which contains fallback values.
+  ///
+  /// Typical usage is as follows:
+  ///
+  /// ```dart
+  /// DefaultTextStyle style = DefaultTextStyle.of(context);
+  /// ```
   static DefaultTextStyle of(BuildContext context) {
     return context.inheritFromWidgetOfExactType(DefaultTextStyle) ?? const DefaultTextStyle.fallback();
   }

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

@@ -44,6 +44,12 @@ class TickerMode extends InheritedWidget {
   /// enabled or disabled.
   ///
   /// In the absence of a [TickerMode] widget, this function defaults to true.
+  ///
+  /// Typical usage is as follows:
+  ///
+  /// ```dart
+  /// bool tickingEnabled = TickerMode.of(context);
+  /// ```
   static bool of(BuildContext context) {
     TickerMode widget = context.inheritFromWidgetOfExactType(TickerMode);
     return widget?.enabled ?? true;