Add dartdoc for image classes

 - Adds dartdoc for all the `of` functions.
 - Renames Image to RawImage. This widget is rarely used and shouldn't take up
   such a nice global name.

Fixes #361

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

@@ -18,6 +18,7 @@ class IconTheme extends InheritedWidget {
 
   final IconThemeData data;
 
+  /// The data from the closest instance of this class that encloses the given context.
   static IconThemeData of(BuildContext context) {
     IconTheme result = context.inheritFromWidgetOfType(IconTheme);
     return result?.data;

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

@@ -93,6 +93,7 @@ class Material extends StatefulComponent {
   final Color color;
   final TextStyle textStyle;
 
+  /// The ink controller from the closest instance of this class that encloses the given context.
   static MaterialInkController of(BuildContext context) {
     final RenderInkFeatures result = context.ancestorRenderObjectOfType(RenderInkFeatures);
     return result;

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

@@ -23,6 +23,9 @@ class ButtonTheme extends InheritedWidget {
 
   final ButtonColor color;
 
+  /// The color from the closest instance of this class that encloses the given context.
+  ///
+  /// Defaults to [ButtonColor.normal] if none exists.
   static ButtonColor of(BuildContext context) {
     ButtonTheme result = context.inheritFromWidgetOfType(ButtonTheme);
     return result?.color ?? ButtonColor.normal;

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

@@ -111,6 +111,7 @@ class Scaffold extends StatefulComponent {
   final Widget floatingActionButton;
   final Widget drawer;
 
+  /// The state from the closest instance of this class that encloses the given context.
   static ScaffoldState of(BuildContext context) => context.ancestorStateOfType(ScaffoldState);
 
   ScaffoldState createState() => new ScaffoldState();

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

@@ -22,9 +22,12 @@ class Theme extends InheritedWidget {
 
   static final ThemeData _kFallbackTheme = new ThemeData.fallback();
 
+  /// The data from the closest instance of this class that encloses the given context.
+  ///
+  /// Defaults to the fallback theme data if none exists.
   static ThemeData of(BuildContext context) {
     Theme theme = context.inheritFromWidgetOfType(Theme);
-    return theme == null ? _kFallbackTheme : theme.data;
+    return theme?.data ?? _kFallbackTheme;
   }
 
   bool updateShouldNotify(Theme old) => data != old.data;

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

@@ -630,6 +630,10 @@ class BackgroundImage {
   final ColorFilter colorFilter;
 
   /// How to align the image within its bounds.
+  ///
+  /// An alignment of (0.0, 0.0) aligns the image to the top-left corner of its
+  /// layout bounds.  An alignment of (1.0, 0.5) aligns the image to the middle
+  /// of the right edge of its layout bounds.
   final FractionalOffset alignment;
 
   /// The image to be painted into the background.

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

@@ -49,6 +49,9 @@ class RenderImage extends RenderBox {
   }
 
   /// If non-null, requires the image to have this width.
+  ///
+  /// If null, the image will pick a size that best preserves its intrinsic
+  /// aspect ratio.
   double get width => _width;
   double _width;
   void set width (double value) {
@@ -58,7 +61,10 @@ class RenderImage extends RenderBox {
     markNeedsLayout();
   }
 
-  /// If non-null, requires the image to have this height.
+  /// If non-null, require the image to have this height.
+  ///
+  /// If null, the image will pick a size that best preserves its intrinsic
+  /// aspect ratio.
   double get height => _height;
   double _height;
   void set height (double value) {
@@ -98,7 +104,7 @@ class RenderImage extends RenderBox {
     markNeedsPaint();
   }
 
-  /// Not yet implemented.
+  /// How to repeat this image if it doesn't fill its layout bounds.
   ImageRepeat get repeat => _repeat;
   ImageRepeat _repeat;
   void set repeat (ImageRepeat value) {

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

@@ -18,6 +18,7 @@ class LocaleQuery<T extends LocaleQueryData> extends InheritedWidget {
 
   final T data;
 
+  /// The data from the closest instance of this class that encloses the given context.
   static LocaleQueryData of(BuildContext context) {
     LocaleQuery query = context.inheritFromWidgetOfType(LocaleQuery);
     return query == null ? null : query.data;

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

@@ -52,7 +52,7 @@ class MediaQuery extends InheritedWidget {
   /// The result of media queries in this subtree.
   final MediaQueryData data;
 
-  /// Returns the media query data for the given context.
+  /// The data from the closest instance of this class that encloses the given context.
   ///
   /// 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,

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

@@ -57,7 +57,7 @@ class Overlay extends StatefulComponent {
   /// The entries to include in the overlay initially.
   final List<OverlayEntry> initialEntries;
 
-  /// The closest enclosing overlay of the given context.
+  /// The state from the closest instance of this class that encloses the given context.
   static OverlayState of(BuildContext context) => context.ancestorStateOfType(OverlayState);
 
   OverlayState createState() => new OverlayState();

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

@@ -84,7 +84,9 @@ class PageStorage extends StatelessComponent {
   final Widget child;
   final PageStorageBucket bucket;
 
-  /// Might return null if there is no PageStorage in this context.
+  /// The bucket from the closest instance of this class that encloses the given context.
+  ///
+  /// Returns null if none exists.
   static PageStorageBucket of(BuildContext context) {
     PageStorage widget = context.ancestorWidgetOfType(PageStorage);
     return widget?.bucket;

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

@@ -384,6 +384,9 @@ abstract class ModalRoute<T> extends TransitionRoute<T> with LocalHistoryRoute<T
 
   final RouteSettings settings;
 
+  /// Returns the modal route most closely associated with the given context.
+  ///
+  /// Returns null if the given context is not associated with a modal route.
   static ModalRoute of(BuildContext context) {
     _ModalScopeStatus widget = context.inheritFromWidgetOfType(_ModalScopeStatus);
     return widget?.route;

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

@@ -57,7 +57,7 @@ abstract class Scrollable extends StatefulComponent {
   final SnapOffsetCallback snapOffsetCallback;
   final double snapAlignmentOffset;
 
-  /// Returns the closest enclosing scrollable for the given context.
+  /// The state from the closest instance of this class that encloses the given context.
   static ScrollableState of(BuildContext context) {
     return context.ancestorStateOfType(ScrollableState);
   }