Add dartdoc to typography.dart (#3576)

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

@@ -2,16 +2,31 @@
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
-// See http://www.google.com/design/spec/style/typography.html
 
 import 'package:flutter/painting.dart';
 
 import 'colors.dart';
 
-// TODO(eseidel): Font weights are supposed to be language relative!
-// TODO(jackson): Baseline should be language relative!
+// TODO(eseidel): Font weights are supposed to be language relative.
+// TODO(jackson): Baseline should be language relative.
 // These values are for English-like text.
 // TODO(ianh): There's no font-family specified here.
+
+/// Material design text theme.
+///
+/// Definitions for the various typographical styles found in material design
+/// (e.g., headline, caption). Rather than creating a [TextTheme] directly,
+/// you can obtain an instance as [Typography.black] or [Typography.white].
+///
+/// To obtain the current text theme, call [Theme.of] with the current
+/// [BuildContext] and read the [ThemeData.textTheme] property.
+///
+/// See also:
+///
+///  * [Typography]
+///  * [Theme]
+///  * [ThemeData]
+///  * <http://www.google.com/design/spec/style/typography.html>
 class TextTheme {
 
   const TextTheme._(this.display4, this.display3, this.display2, this.display1, this.headline, this.title, this.subhead, this.body2, this.body1, this.caption, this.button);
@@ -42,18 +57,44 @@ class TextTheme {
       caption  = const TextStyle(inherit: false, fontSize:  12.0, fontWeight: FontWeight.w400, color: Colors.white70, textBaseline: TextBaseline.alphabetic),
       button   = const TextStyle(inherit: false, fontSize:  14.0, fontWeight: FontWeight.w500, color: Colors.white,   textBaseline: TextBaseline.alphabetic);
 
+  /// Extremely large text.
+  ///
+  /// The font size is 112 pixels.
   final TextStyle display4;
+
+  /// Very, very large text.
+  ///
+  /// Used for the date in [DatePicker].
   final TextStyle display3;
+
+  /// Very large text.
   final TextStyle display2;
+
+  /// Large text.
   final TextStyle display1;
+
+  /// Used for large text in dialogs (e.g., the month and year in [DatePicker]).
   final TextStyle headline;
+
+  /// Used for the primary text in app bars and dialogs (e.g., [AppBar.title] and [Dialog.title]).
   final TextStyle title;
+
+  /// Used for the primary text in lists (e.g., [ListItem.title]).
   final TextStyle subhead;
+
+  /// Used for emphasizing text that would otherwise be [body1].
   final TextStyle body2;
+
+  /// Used for the default text style for [Material].
   final TextStyle body1;
+
+  /// Used for auxillary text associted with images.
   final TextStyle caption;
+
+  /// Used for text on [RaisedButton] and [FlatButton].
   final TextStyle button;
 
+  /// Linearly interpolate between two text themes.
   static TextTheme lerp(TextTheme begin, TextTheme end, double t) {
     return new TextTheme._(
       TextStyle.lerp(begin.display4, end.display4, t),
@@ -69,11 +110,30 @@ class TextTheme {
       TextStyle.lerp(begin.button, end.button, t)
     );
   }
-
 }
 
+/// The two material design text themes.
+///
+/// [Typography.black] and [Typography.white] define the two text themes used in
+/// material design. The black text theme, which uses darkly colored glyphs, is
+/// used on lightly colored backgrounds in light themes. The white text theme,
+/// which uses lightly colored glyphs, is used on darkly colored backgrounds in
+/// in light themes and in dark themes.
+///
+/// To obtain the current text theme, call [Theme.of] with the current
+/// [BuildContext] and read the [ThemeData.textTheme] property.
+///
+/// See also:
+///
+///  * [Theme]
+///  * [ThemeData]
+///  * <http://www.google.com/design/spec/style/typography.html>
 class Typography {
   Typography._();
+
+  /// A material design text theme with darkly colored glyphs.
   static const TextTheme black = const TextTheme._black();
+
+  /// A material design text theme with lightly colored glyphs.
   static const TextTheme white = const TextTheme._white();
 }