Merge pull request #2465 from abarth/ui_docs

Add more dartdoc to dart:ui

sky/engine/core/compositing/SceneBuilder.cpp

@@ -66,7 +66,7 @@ FOR_EACH_BINDING(DART_REGISTER_NATIVE)
   });
 }
 
-SceneBuilder::SceneBuilder(const Rect& bounds)
+SceneBuilder::SceneBuilder()
     : m_currentLayer(nullptr)
     , m_currentRasterizerTracingThreshold(0)
 {

sky/engine/core/compositing/SceneBuilder.h

@@ -28,8 +28,8 @@ namespace blink {
 class SceneBuilder : public RefCounted<SceneBuilder>, public DartWrappable {
     DEFINE_WRAPPERTYPEINFO();
 public:
-    static PassRefPtr<SceneBuilder> create(const Rect& bounds) {
-      return adoptRef(new SceneBuilder(bounds));
+    static PassRefPtr<SceneBuilder> create() {
+      return adoptRef(new SceneBuilder());
     }
 
     ~SceneBuilder() override;
@@ -57,7 +57,7 @@ public:
     static void RegisterNatives(DartLibraryNatives* natives);
 
 private:
-    explicit SceneBuilder(const Rect& bounds);
+    explicit SceneBuilder();
 
     void addLayer(std::unique_ptr<flow::ContainerLayer> layer);
 

sky/engine/core/dart/compositing.dart

@@ -4,31 +4,119 @@
 
 part of dart_ui;
 
+/// An opaque object representing a composited scene.
 abstract class Scene extends NativeFieldWrapperClass2 {
+  /// Releases the resources used by this scene.
+  ///
+  /// After calling this function, the scene is cannot be used further.
   void dispose() native "Scene_dispose";
 }
 
+/// Builds a [Scene] containing the given visuals.
 class SceneBuilder extends NativeFieldWrapperClass2 {
-  void _constructor(Rect bounds) native "SceneBuilder_constructor";
-  SceneBuilder(Rect bounds) { _constructor(bounds); }
+  // TODO(abarth): Remove this ignored "bounds" argument.
+  SceneBuilder([Rect bounds]) { _constructor(); }
+  void _constructor() native "SceneBuilder_constructor";
 
+  /// Pushes a transform operation onto the operation stack.
+  ///
+  /// The objects are transformed by the given matrix before rasterization.
+  ///
+  /// See [pop] for details about the operation stack.
   void pushTransform(Float64List matrix4) native "SceneBuilder_pushTransform";
+
+  /// Pushes a rectangular clip operation onto the operation stack.
+  ///
+  /// Rasterization outside the given rectangle is discarded.
+  ///
+  /// See [pop] for details about the operation stack.
   void pushClipRect(Rect rect) native "SceneBuilder_pushClipRect";
+
+  /// Pushes a rounded-rectangular clip operation onto the operation stack.
+  ///
+  /// Rasterization outside the given rounded rectangle is discarded.
+  ///
+  /// See [pop] for details about the operation stack.
   void pushClipRRect(RRect rrect) native "SceneBuilder_pushClipRRect";
+
+  /// Pushes a path clip operation onto the operation stack.
+  ///
+  /// Rasterization outside the given path is discarded.
+  ///
+  /// See [pop] for details about the operation stack.
   void pushClipPath(Path path) native "SceneBuilder_pushClipPath";
+
+  /// Pushes an opacity operation onto the operation stack.
+  ///
+  /// The given alpha value is blended into the alpha value of the objects'
+  /// rasterization. An alpha value of 0 makes the objects entirely invisible.
+  /// An alpha value of 255 has no effect (i.e., the objects retain the current
+  /// opacity).
+  ///
+  /// See [pop] for details about the operation stack.
   void pushOpacity(int alpha) native "SceneBuilder_pushOpacity";
+
+  /// Pushes a color filter operation onto the operation stack.
+  ///
+  /// The given color is applied to the objects' rasterization using the given
+  /// transfer mode.
+  ///
+  /// See [pop] for details about the operation stack.
   void pushColorFilter(Color color, TransferMode transferMode) native "SceneBuilder_pushColorFilter";
+
+  /// Pushes a shader mask operation onto the operation stack.
+  ///
+  /// The given shader is applied to the object's rasterization in the given
+  /// rectangle using the given transfer mode.
+  ///
+  /// See [pop] for details about the operation stack.
   void pushShaderMask(Shader shader, Rect maskRect, TransferMode transferMode) native "SceneBuilder_pushShaderMask";
 
+  /// Ends the effect of the most recently pushed operation.
+  ///
+  /// Internally the scene builder maintains a stack of operations. Each of the
+  /// operations in the stack applies to each of the objects added to the scene.
+  /// Calling this function removes the most recently added operation from the
+  /// stack.
   void pop() native "SceneBuilder_pop";
 
+  /// Adds an object to the scene that displays performance statistics.
+  ///
+  /// Useful during development to assess the performance of the application.
+  /// The enabledOptions controls which statistics are displayed. The bounds
+  /// controls where the statistics are displayed.
   void addPerformanceOverlay(int enabledOptions, Rect bounds) native "SceneBuilder_addPerformanceOverlay";
+
+  /// Adds a picture to the scene.
+  ///
+  /// The picture is rasterized at the given offset.
   void addPicture(Offset offset, Picture picture) native "SceneBuilder_addPicture";
+
+  /// (mojo-only) Adds a scene rendered by another application to the scene for
+  /// this application.
+  ///
+  /// Applications typically obtain scene tokens when embedding other views via
+  /// the Mojo view manager, but this function is agnostic as to the source of
+  /// scene token.
   void addChildScene(Offset offset,
                      int physicalWidth,
                      int physicalHeight,
                      int sceneToken) native "SceneBuilder_addChildScene";
+
+  /// Sets a threshold after which additional debugging information should be recorded.
+  ///
+  /// Currently this interface is difficult to use by end-developers. If you're
+  /// interested in using this feature, please contact [flutter-dev](https://groups.google.com/forum/#!forum/flutter-dev).
+  /// We'll hopefully be able to figure out how to make this feature more useful
+  /// to you.
   void setRasterizerTracingThreshold(int frameInterval) native "SceneBuilder_setRasterizerTracingThreshold";
 
+  /// Finishes building the scene.
+  ///
+  /// Returns a [Scene] containing the objects that have been added to this
+  /// scene builder.
+  ///
+  /// After calling this function, the scene builder object is invalid and
+  /// cannot be used further.
   Scene build() native "SceneBuilder_build";
 }

sky/engine/core/dart/painting.dart

@@ -36,6 +36,14 @@ void decodeImageFromDataPipe(int handle, ImageDecoderCallback callback)
 void decodeImageFromList(Uint8List list, ImageDecoderCallback callback)
     native "decodeImageFromList";
 
+/// A complex, one-dimensional subset of a plane.
+///
+/// A path consists of a number of segments of various types, such as lines,
+/// arcs, or beziers. Paths can be open or closed and can self-intersect. A path
+/// also encloses a (possibly discontiguous) region of the plane based on
+/// whether a line from a given point on the plane to a point at infinity
+/// intersects the path an even (non-enclosed) or and odd (enclosed) number of
+/// times.
 class Path extends NativeFieldWrapperClass2 {
   void _constructor() native "Path_constructor";
   Path() { _constructor(); }
@@ -179,14 +187,30 @@ enum VertexMode {
   triangleFan,
 }
 
+/// An interface for recording graphical operations.
+///
+/// To record graphical operations, first create a [PictureRecorder], then
+/// construct a Canvas using the picture recorder. After issuing all the
+/// graphical operations, call the [endRecording] function on the picture
+/// recorder to obtain the final [Picture]. The [Picture] can then be included
+/// in a composited [Scene] via a [SceneBuilder]. Finally, the [Scene] can be
+/// displayed to the user via the [render] function on [Window].
 class Canvas extends NativeFieldWrapperClass2 {
-  void _constructor(PictureRecorder recorder, Rect bounds) native "Canvas_constructor";
-  Canvas(PictureRecorder recorder, Rect bounds) {
+  void _constructor(PictureRecorder recorder, Rect cullRect) native "Canvas_constructor";
+
+  /// Constructs a canvas for recording graphical operations into the given picture recorder.
+  ///
+  /// Graphical operations that affect pixels entirely outside the given
+  /// cullRect might be discarded by the implementation. However, the
+  /// implementation might draw outside these bounds if, for example, a command
+  /// draws partially inside and outside the cullRect. To ensure that pixels
+  /// outside a given region are discarded, consider using a [clipRect].
+  Canvas(PictureRecorder recorder, Rect cullRect) {
     if (recorder == null)
       throw new ArgumentError("[recorder] argument cannot be null.");
     if (recorder.isRecording)
       throw new ArgumentError("You must call endRecording() before reusing a PictureRecorder to create a new Canvas object.");
-    _constructor(recorder, bounds);
+    _constructor(recorder, cullRect);
   }
 
   void save() native "Canvas_save";
@@ -304,8 +328,9 @@ class Canvas extends NativeFieldWrapperClass2 {
   }
 }
 
+/// An object representing a sequence of recorded graphical operations.
 abstract class Picture extends NativeFieldWrapperClass2 {
-  /// Replays the drawing commands on the specified canvas. Note that
+  /// Replays the graphical operations on the specified canvas. Note that
   /// this has the effect of unfurling this picture into the destination
   /// canvas. Using the Canvas drawPicture entry point gives the destination
   /// canvas the option of just taking a ref.
@@ -316,10 +341,23 @@ abstract class Picture extends NativeFieldWrapperClass2 {
   void dispose() native "Picture_dispose";
 }
 
+/// Records a [Picture] containing a sequence of graphical operations.
+///
+/// To begin recording, construct a [Canvas] to record the commands.
 class PictureRecorder extends NativeFieldWrapperClass2 {
   void _constructor() native "PictureRecorder_constructor";
   PictureRecorder() { _constructor(); }
 
+  /// Whether this object is currently recording commands.
+  ///
+  /// Specifically, whether a [Canvas] object has been created to record
+  /// commands and recording has not yet ended.
   bool get isRecording native "PictureRecorder_isRecording";
+
+  /// Finishes recording graphical operations.
+  ///
+  /// Returns a picture containing the graphical operations that have been
+  /// recorded thus far. After calling this function, both the picture recorder
+  /// and the canvas objects are invalid and cannot be used further.
   Picture endRecording() native "PictureRecorder_endRecording";
 }

sky/engine/core/dart/text.dart

@@ -17,6 +17,7 @@ enum FontStyle {
 class FontWeight {
   const FontWeight._(this.index);
 
+  /// The encoded integer value of this font weight.
   final int index;
 
   /// Thin, the least thick
@@ -46,13 +47,21 @@ class FontWeight {
   /// Black, the most thick
   static const FontWeight w900 = const FontWeight._(8);
 
+  /// The default font weight.
   static const FontWeight normal = w400;
+
+  /// A commonly used font weight that is heavier than normal.
   static const FontWeight bold = w700;
 
+  /// A list of all the font weights.
   static const List<FontWeight> values = const [
     w100, w200, w300, w400, w500, w600, w700, w800, w900
   ];
 
+  /// Linearly interpolates between two font weights.
+  ///
+  /// Rather than using fractional weights, the interpolation rounds to the
+  /// nearest weight.
   static FontWeight lerp(FontWeight begin, FontWeight end, double t) {
     return values[lerpDouble(begin?.index ?? normal.index, end?.index ?? normal.index, t.clamp(0.0, 1.0)).round()];
   }
@@ -251,7 +260,21 @@ Int32List _encodeTextStyle(Color color,
   return result;
 }
 
+/// An opaque object that determines the size, position, and rendering of text.
 class TextStyle {
+  /// Constructs a new TextStyle object.
+  ///
+  /// * [color] The color to use when painting the text.
+  /// * [decoration] The decorations to paint near the text (e.g., an underline).
+  /// * [decorationColor] The color in which to paint the text decorations.
+  /// * [decorationStyle] The style in which to paint the text decorations (e.g., dashed).
+  /// * [fontWeight] The typeface thickness to use when painting the text (e.g., bold).
+  /// * [fontStyle] The typeface variant to use when drawing the letters (e.g., italics).
+  /// * [fontFamily] The name of the font to use when painting the text (e.g., Roboto).
+  /// * [fontSize] The size of gyphs (in logical pixels) to use when painting the text.
+  /// * [letterSpacing] The amount of space (in logical pixels) to add between each letter.
+  /// * [wordSpacing] The amount of space (in logical pixels) to add at each sequence of white-space (i.e. between each word).
+  /// * [lineHeight] The distance between the text baselines, as a multiple of the font size.
   TextStyle({
     Color color,
     TextDecoration decoration,
@@ -357,7 +380,13 @@ Int32List _encodeParagraphStyle(TextAlign textAlign,
   return result;
 }
 
+/// An opaque object that determines the position of lines within a paragraph of text.
 class ParagraphStyle {
+  /// Constructs a new ParagraphStyle object.
+  ///
+  /// * [textAlign] .
+  /// * [textBaseline] .
+  /// * [lineHeight] .
   ParagraphStyle({
     TextAlign textAlign,
     TextBaseline textBaseline,
@@ -514,23 +543,65 @@ class TextPosition {
   }
 }
 
+/// A paragraph of text.
+///
+/// A paragraph retains the size and position of each glyph in the text and can
+/// be efficiently resized and painted.
 abstract class Paragraph extends NativeFieldWrapperClass2 {
+  /// The minimum amount of horizontal space this paragraph of text is permitted to occupy.
   double get minWidth native "Paragraph_minWidth";
   void set minWidth(double value) native "Paragraph_setMinWidth";
+
+  /// The maximum amount of horizontal space this paragraph of text is permitted to occupy.
   double get maxWidth native "Paragraph_maxWidth";
   void set maxWidth(double value) native "Paragraph_setMaxWidth";
+
+  /// The minimum amount of vertical space this paragraph of text is permitted to occupy.
   double get minHeight native "Paragraph_minHeight";
   void set minHeight(double value) native "Paragraph_setMinHeight";
+
+  /// The maximum amount of vertical space this paragraph of text is permitted to occupy.
   double get maxHeight native "Paragraph_maxHeight";
   void set maxHeight(double value) native "Paragraph_setMaxHeight";
+
+  /// The amount of horizontal space this paragraph occupies.
+  ///
+  /// Valid only after [layout] has been called.
   double get width native "Paragraph_width";
+
+  /// The amount of vertical space this paragraph occupies.
+  ///
+  /// Valid only after [layout] has been called.
   double get height native "Paragraph_height";
+
+  /// The minimum width that this paragraph could be without failing to paint
+  /// its contents within itself.
+  ///
+  /// Valid only after [layout] has been called.
   double get minIntrinsicWidth native "Paragraph_minIntrinsicWidth";
+
+  /// Returns the smallest width beyond which increasing the width never
+  /// decreases the height.
+  ///
+  /// Valid only after [layout] has been called.
   double get maxIntrinsicWidth native "Paragraph_maxIntrinsicWidth";
+
+  /// The distance from the top of the paragraph to the alphabetic baseline of the first line, in logical pixels.
   double get alphabeticBaseline native "Paragraph_alphabeticBaseline";
+
+  /// The distance from the top of the paragraph to the ideographic baseline of the first line, in logical pixels.
   double get ideographicBaseline native "Paragraph_ideographicBaseline";
 
+  /// Computes the size and position of each glyph in the paragraph.
+  ///
+  /// Setting the [minWidth], [maxWidth], [minHeight], or [maxHeight]
+  /// invalidates the layout of this paragraph, requiring a call to this
+  /// function before painting or reading geometry from this paragraph.
   void layout() native "Paragraph_layout";
+
+  /// Draws the text in this paragraph into the given canvas at the given offset.
+  ///
+  /// Valid only after [layout] has been called.
   void paint(Canvas canvas, Offset offset) native "Paragraph_paint";
 
   /// Returns a list of text boxes that enclose the given text range.
@@ -545,18 +616,35 @@ abstract class Paragraph extends NativeFieldWrapperClass2 {
   }
 }
 
+/// Builds a [Paragraph] containing text with the given styling information.
 class ParagraphBuilder extends NativeFieldWrapperClass2 {
   void _constructor() native "ParagraphBuilder_constructor";
   ParagraphBuilder() { _constructor(); }
 
-  void _pushStyle(Int32List encoded, String fontFamily, double fontSize, double letterSpacing, double wordSpacing, double lineHeight) native "ParagraphBuilder_pushStyle";
+  /// Applies the given style to the added text until [pop] is called.
+  ///
+  /// See [pop] for details.
   void pushStyle(TextStyle style) => _pushStyle(style._encoded, style._fontFamily, style._fontSize, style._letterSpacing, style._wordSpacing, style._lineHeight);
+  void _pushStyle(Int32List encoded, String fontFamily, double fontSize, double letterSpacing, double wordSpacing, double lineHeight) native "ParagraphBuilder_pushStyle";
 
+  /// Ends the effect of the most recent call to [pushStyle].
+  ///
+  /// Internally, the paragraph builder maintains a stack of text styles. Text
+  /// added to the paragraph is affected by all the styles in the stack. Calling
+  /// [pop] removes the topmost style in the stack, leaving the remaining styles
+  /// in effect.
   void pop() native "ParagraphBuilder_pop";
 
+  /// Adds the given text to the paragraph.
+  ///
+  /// The text will be styled according to the current stack of text styles.
   void addText(String text) native "ParagraphBuilder_addText";
 
-  Paragraph _build(Int32List encoded, double lineHeight) native "ParagraphBuilder_build";
+  /// Applies the given paragraph style and returns a Paragraph containing the added text and associated styling.
+  ///
+  /// After calling this function, the paragraph builder object is invalid and
+  /// cannot be used further.
   Paragraph build(ParagraphStyle style) => _build(style._encoded, style._lineHeight);
+  Paragraph _build(Int32List encoded, double lineHeight) native "ParagraphBuilder_build";
 }