Add some missing dartdocs (flutter#8819)

abarth · web-flow · commit dc83c4913a93 · 2017-03-15T20:56:49.000-07:00
diff --git a/packages/flutter/lib/src/foundation/serialization.dart b/packages/flutter/lib/src/foundation/serialization.dart
@@ -13,6 +13,7 @@ import 'package:typed_data/typed_buffers.dart' show Uint8Buffer;
 ///
 /// The byte order used is [Endianness.HOST_ENDIAN] throughout.
 class WriteBuffer {
+  /// Creates an interface for incrementally building a [ByteData] instance.
   WriteBuffer() {
     _buffer = new Uint8Buffer();
     _eightBytes = new ByteData(8);
@@ -23,49 +24,59 @@ class WriteBuffer {
   ByteData _eightBytes;
   Uint8List _eightBytesAsList;
 
+  /// Write a Uint8 into the buffer.
   void putUint8(int byte) {
     _buffer.add(byte);
   }
 
+  /// Write a Uint16 into the buffer.
   void putUint16(int value) {
     _eightBytes.setUint16(0, value, Endianness.HOST_ENDIAN);
     _buffer.addAll(_eightBytesAsList, 0, 2);
   }
 
+  /// Write a Uint32 into the buffer.
   void putUint32(int value) {
     _eightBytes.setUint32(0, value, Endianness.HOST_ENDIAN);
     _buffer.addAll(_eightBytesAsList, 0, 4);
   }
 
+  /// Write an Int32 into the buffer.
   void putInt32(int value) {
     _eightBytes.setInt32(0, value, Endianness.HOST_ENDIAN);
     _buffer.addAll(_eightBytesAsList, 0, 4);
   }
 
+  /// Write an Int64 into the buffer.
   void putInt64(int value) {
     _eightBytes.setInt64(0, value, Endianness.HOST_ENDIAN);
     _buffer.addAll(_eightBytesAsList, 0, 8);
   }
 
+  /// Write an Float64 into the buffer.
   void putFloat64(double value) {
     _eightBytes.setFloat64(0, value, Endianness.HOST_ENDIAN);
     _buffer.addAll(_eightBytesAsList);
   }
 
+  /// Write all the values from a [Uint8List] into the buffer.
   void putUint8List(Uint8List list) {
     _buffer.addAll(list);
   }
 
+  /// Write all the values from a [Int32List] into the buffer.
   void putInt32List(Int32List list) {
     _alignTo(4);
     _buffer.addAll(list.buffer.asUint8List(list.offsetInBytes, 4 * list.length));
   }
 
+  /// Write all the values from an [Int64List] into the buffer.
   void putInt64List(Int64List list) {
     _alignTo(8);
     _buffer.addAll(list.buffer.asUint8List(list.offsetInBytes, 8 * list.length));
   }
 
+  /// Write all the values from a [Float64List] into the buffer.
   void putFloat64List(Float64List list) {
     _alignTo(8);
     _buffer.addAll(list.buffer.asUint8List(list.offsetInBytes, 8 * list.length));
@@ -79,6 +90,7 @@ class WriteBuffer {
     }
   }
 
+  /// Finalize and return the written [ByteData].
   ByteData done() {
     final ByteData result = _buffer.buffer.asByteData(0, _buffer.lengthInBytes);
     _buffer = null;
@@ -90,80 +102,94 @@ class WriteBuffer {
 ///
 /// The byte order used is [Endianness.HOST_ENDIAN] throughout.
 class ReadBuffer {
-  final ByteData data;
-  int position = 0;
-
   /// Creates a [ReadBuffer] for reading from the specified [data].
   ReadBuffer(this.data) {
     assert(data != null);
   }
 
+  /// The underlying data being read.
+  final ByteData data;
+
+  /// The position to read next.
+  int _position = 0;
+
+  /// Whether the buffer has data remaining to read.
+  bool get hasRemaining => _position < data.lengthInBytes;
+
+  /// Reads a Uint8 from the buffer.
   int getUint8() {
-    return data.getUint8(position++);
+    return data.getUint8(_position++);
   }
 
+  /// Reads a Uint16 from the buffer.
   int getUint16() {
-    final int value = data.getUint16(position, Endianness.HOST_ENDIAN);
-    position += 2;
+    final int value = data.getUint16(_position, Endianness.HOST_ENDIAN);
+    _position += 2;
     return value;
   }
 
+  /// Reads a Uint32 from the buffer.
   int getUint32() {
-    final int value = data.getUint32(position, Endianness.HOST_ENDIAN);
-    position += 4;
+    final int value = data.getUint32(_position, Endianness.HOST_ENDIAN);
+    _position += 4;
     return value;
   }
 
+  /// Reads an Int32 from the buffer.
   int getInt32() {
-    final int value = data.getInt32(position, Endianness.HOST_ENDIAN);
-    position += 4;
+    final int value = data.getInt32(_position, Endianness.HOST_ENDIAN);
+    _position += 4;
     return value;
   }
 
+  /// Reads an Int64 from the buffer.
   int getInt64() {
-    final int value = data.getInt64(position, Endianness.HOST_ENDIAN);
-    position += 8;
+    final int value = data.getInt64(_position, Endianness.HOST_ENDIAN);
+    _position += 8;
     return value;
   }
 
+  /// Reads a Float64 from the buffer.
   double getFloat64() {
-    final double value = data.getFloat64(position, Endianness.HOST_ENDIAN);
-    position += 8;
+    final double value = data.getFloat64(_position, Endianness.HOST_ENDIAN);
+    _position += 8;
     return value;
   }
 
+  /// Reads the given number of Uint8s from the buffer.
   Uint8List getUint8List(int length) {
-    final Uint8List list = data.buffer.asUint8List(data.offsetInBytes + position, length);
-    position += length;
+    final Uint8List list = data.buffer.asUint8List(data.offsetInBytes + _position, length);
+    _position += length;
     return list;
   }
 
+  /// Reads the given number of Int32s from the buffer.
   Int32List getInt32List(int length) {
     _alignTo(4);
-    final Int32List list = data.buffer.asInt32List(data.offsetInBytes + position, length);
-    position += 4 * length;
+    final Int32List list = data.buffer.asInt32List(data.offsetInBytes + _position, length);
+    _position += 4 * length;
     return list;
   }
 
+  /// Reads the given number of Int64s from the buffer.
   Int64List getInt64List(int length) {
     _alignTo(8);
-    final Int64List list = data.buffer.asInt64List(data.offsetInBytes + position, length);
-    position += 8 * length;
+    final Int64List list = data.buffer.asInt64List(data.offsetInBytes + _position, length);
+    _position += 8 * length;
     return list;
   }
 
+  /// Reads the given number of Float64s from the buffer.
   Float64List getFloat64List(int length) {
     _alignTo(8);
-    final Float64List list = data.buffer.asFloat64List(data.offsetInBytes + position, length);
-    position += 8 * length;
+    final Float64List list = data.buffer.asFloat64List(data.offsetInBytes + _position, length);
+    _position += 8 * length;
     return list;
   }
 
   void _alignTo(int alignment) {
-    final int mod = position % alignment;
+    final int mod = _position % alignment;
     if (mod != 0)
-      position += alignment - mod;
+      _position += alignment - mod;
   }
-
-  bool get hasRemaining => position < data.lengthInBytes;
 }
diff --git a/packages/flutter/lib/src/rendering/layer.dart b/packages/flutter/lib/src/rendering/layer.dart
@@ -522,7 +522,16 @@ class BackdropFilterLayer extends ContainerLayer {
   }
 }
 
+/// A composited layer that uses a physical model to producing lighting effects.
+///
+/// For example, the layer casts a shadow according to its geometry and the
+/// relative position of lights and other physically modelled objects in the
+/// scene.
 class PhysicalModelLayer extends ContainerLayer {
+  /// Creates a composited layer that uses a physical model to producing
+  /// lighting effects.
+  ///
+  /// The [clipRRect], [elevation], and [color] arguments must not be null.
   PhysicalModelLayer({
     @required this.clipRRect,
     @required this.elevation,
diff --git a/packages/flutter/lib/src/services/message_codecs.dart b/packages/flutter/lib/src/services/message_codecs.dart
@@ -11,6 +11,8 @@ import 'message_codec.dart';
 
 /// [MessageCodec] with unencoded binary messages represented using [ByteData].
 class BinaryCodec implements MessageCodec<ByteData> {
+  /// Creates a [MessageCodec] with unencoded binary messages represented using
+  /// [ByteData].
   const BinaryCodec();
 
   @override
@@ -22,6 +24,7 @@ class BinaryCodec implements MessageCodec<ByteData> {
 
 /// [MessageCodec] with UTF-8 encoded String messages.
 class StringCodec implements MessageCodec<String> {
+  /// Creates a [MessageCodec] with UTF-8 encoded String messages.
   const StringCodec();
 
   @override
@@ -54,6 +57,8 @@ class JSONMessageCodec implements MessageCodec<dynamic> {
   // The codec serializes messages as defined by the JSON codec of the
   // dart:convert package. The format used must match the Android and
   // iOS counterparts.
+
+  /// Creates a [MessageCodec] with UTF-8 encoded JSON messages.
   const JSONMessageCodec();
 
   @override
@@ -72,6 +77,7 @@ class JSONMessageCodec implements MessageCodec<dynamic> {
 }
 
 /// [MethodCodec] with UTF-8 encoded JSON method calls and result envelopes.
+///
 /// Values supported as method arguments and result payloads are those supported
 /// by [JSONMessageCodec].
 class JSONMethodCodec implements MethodCodec {
@@ -87,6 +93,9 @@ class JSONMethodCodec implements MethodCodec {
   //     element, or
   //   * three-element lists containing, in order, an error code String, an
   //     error message String, and an error details value.
+
+  /// Creates a [MethodCodec] with UTF-8 encoded JSON method calls and result
+  /// envelopes.
   const JSONMethodCodec();
 
   @override
@@ -185,6 +194,7 @@ class StandardMessageCodec implements MessageCodec<dynamic> {
   static const int _kList = 12;
   static const int _kMap = 13;
 
+  /// Creates a [MessageCodec] using the Flutter standard binary encoding.
   const StandardMessageCodec();
 
   @override
@@ -379,6 +389,7 @@ class StandardMethodCodec implements MethodCodec {
   //   * In the error case, the concatenation of the encoding of the error code
   //     string, the error message string, and the error details value.
 
+  /// Creates a [MethodCodec] using the Flutter standard binary encoding.
   const StandardMethodCodec();
 
   @override
diff --git a/packages/flutter/lib/src/widgets/framework.dart b/packages/flutter/lib/src/widgets/framework.dart
@@ -2563,9 +2563,7 @@ abstract class Element implements BuildContext {
     if (_dirty)
       owner.scheduleBuildFor(this);
     if (hadDependencies)
-      didChangeDependencies
-      
-      ();
+      didChangeDependencies();
   }
 
   /// Transition from the "active" to the "inactive" lifecycle state.
@@ -3047,9 +3045,9 @@ abstract class ComponentElement extends Element {
     rebuild();
   }
 
-  /// Calls the `build` method of the [StatelessWidget] object (for
-  /// stateless widgets) or the [State] object (for stateful widgets) and
-  /// then updates the widget tree.
+  /// Calls the [StatelessWidget.build] method of the [StatelessWidget] object
+  /// (for stateless widgets) or the [State.build] method of the [State] object
+  /// (for stateful widgets) and then updates the widget tree.
   ///
   /// Called automatically during [mount] to generate the first build, and by
   /// [rebuild] when the element needs updating.
@@ -3091,6 +3089,9 @@ abstract class ComponentElement extends Element {
     });
   }
 
+  /// Subclasses should override this function to actually call the appropriate
+  /// `build` function (e.g., [StatelessWidget.build] or [State.build]) for
+  /// their widget.
   @protected
   Widget build();
 
diff --git a/packages/flutter/lib/src/widgets/heroes.dart b/packages/flutter/lib/src/widgets/heroes.dart
@@ -416,10 +416,13 @@ class _HeroFlight {
 class HeroController extends NavigatorObserver {
   /// Creates a hero controller with the given [RectTween] constructor if any.
   ///
-  /// The [createRectTween] argument is optional. If null, a linear
-  /// [RectTween] is used.
+  /// The [createRectTween] argument is optional. If null, the controller uses a
+  /// linear [RectTween].
   HeroController({ this.createRectTween });
 
+  /// Used to create [RectTween]s that interpolate the position of heros in flight.
+  ///
+  /// If null, the controller uses a linear [RectTween].
   final CreateRectTween createRectTween;
 
   // Disable Hero animations while a user gesture is controlling the navigation.
diff --git a/packages/flutter/lib/src/widgets/pages.dart b/packages/flutter/lib/src/widgets/pages.dart
@@ -62,6 +62,10 @@ Widget _defaultTransitionsBuilder(BuildContext context, Animation<double> animat
 /// Callers must define the [pageBuilder] function which creates the route's
 /// primary contents. To add transitions define the [transitionsBuilder] function.
 class PageRouteBuilder<T> extends PageRoute<T> {
+  /// Creates a route that deletates to builder callbacks.
+  ///
+  /// The [pageBuilder], [transitionsBuilder], [opaque], [barrierDismissable],
+  /// and [maintainState] arguments must not be null.
   PageRouteBuilder({
     RouteSettings settings: const RouteSettings(),
     this.pageBuilder,
@@ -79,7 +83,14 @@ class PageRouteBuilder<T> extends PageRoute<T> {
     assert(maintainState != null);
   }
 
+  /// Used build the route's primary contents.
+  ///
+  /// See [ModalRoute.buildPage] for complete definition of the parameters.
   final RoutePageBuilder pageBuilder;
+
+  /// Used to build the route's transitions.
+  ///
+  /// See [ModalRoute.buildTransitions] for complete definition of the parameters.
   final RouteTransitionsBuilder transitionsBuilder;
 
   @override
diff --git a/packages/flutter/lib/src/widgets/text_selection.dart b/packages/flutter/lib/src/widgets/text_selection.dart
@@ -63,8 +63,8 @@ abstract class TextSelectionDelegate {
   void hideToolbar();
 }
 
-// An interface for building the selection UI, to be provided by the
-// implementor of the toolbar widget.
+/// An interface for building the selection UI, to be provided by the
+/// implementor of the toolbar widget.
 abstract class TextSelectionControls {
   /// Builds a selection handle of the given type.
   Widget buildHandle(BuildContext context, TextSelectionHandleType type);
