Address review comments on prior patch (#4270)
I pulled the trigger to land the previous patch too quickly and missed a
number of comments.
diff --git a/examples/flutter_gallery/lib/gallery/syntax_highlighter.dart b/examples/flutter_gallery/lib/gallery/syntax_highlighter.dart
index 2c7eabb..4367ece 100644
--- a/examples/flutter_gallery/lib/gallery/syntax_highlighter.dart
+++ b/examples/flutter_gallery/lib/gallery/syntax_highlighter.dart
@@ -234,7 +234,7 @@
continue;
}
- // Metadata
+ // Meta data
if (_scanner.scan(new RegExp(r"@\w+"))) {
_spans.add(new _HighlightSpan(
_HighlightType.keyword,
diff --git a/packages/flutter/lib/src/rendering/proxy_box.dart b/packages/flutter/lib/src/rendering/proxy_box.dart
index 097b8cc..71577bc 100644
--- a/packages/flutter/lib/src/rendering/proxy_box.dart
+++ b/packages/flutter/lib/src/rendering/proxy_box.dart
@@ -832,6 +832,9 @@
}
/// Applies a filter to the existing painted content and then paints [child].
+///
+/// This effect is relatively expensive, especially if the filter is non-local,
+/// such as a blur.
class RenderBackdropFilter extends RenderProxyBox {
/// Creates a backdrop filter.
///
@@ -930,7 +933,7 @@
/// Clips its child using a rectangle.
///
/// By default, [RenderClipRect] prevents its child from painting outside its
-/// bounds, but the size and location of the clip can be customized using a
+/// bounds, but the size and location of the clip rect can be customized using a
/// custom [clipper].
class RenderClipRect extends _RenderCustomClip<Rect> {
/// Creates a rectangular clip.
@@ -1021,9 +1024,9 @@
/// Clips its child using an oval.
///
-/// By default, inscribes an oval into its layout dimensions and prevents its
-/// child from painting outside that oval, but the size and location of the clip
-/// can be customized using a custom [clipper].
+/// By default, inscribes an axis-aligned oval into its layout dimensions and
+/// prevents its child from painting outside that oval, but the size and
+/// location of the clip oval can be customized using a custom [clipper].
class RenderClipOval extends _RenderCustomClip<Rect> {
/// Creates an oval-shaped clip.
///
@@ -1551,12 +1554,12 @@
/// Provides a canvas on which to draw during the paint phase.
///
-/// When asked to paint, [CustomPaint] first ask its [painter] to paint on the
-/// current canvas, then it paints its child, and then, after painting its
-/// child, it ask its [foregroundPainter] to paint. The coodinate system of the
-/// canvas matches the coordinate system of the [CustomPaint] object. The
+/// When asked to paint, [RenderCustomPaint] first asks its [painter] to paint
+/// on the current canvas, then it paints its child, and then, after painting
+/// its child, it asks its [foregroundPainter] to paint. The coodinate system of
+/// the canvas matches the coordinate system of the [CustomPaint] object. The
/// painters are expected to paint within a rectangle starting at the origin and
-/// encompassing a region of the given size. (If the painters paints outside
+/// encompassing a region of the given size. (If the painters paint outside
/// those bounds, there might be insufficient memory allocated to rasterize the
/// painting commands and the resulting behavior is undefined.)
///
@@ -1568,10 +1571,10 @@
///
/// See also:
///
-/// * [CustomPainter],
+/// * [CustomPainter]
/// * [Canvas]
class RenderCustomPaint extends RenderProxyBox {
- /// Creates a render object that delgates its painting.
+ /// Creates a render object that delegates its painting.
RenderCustomPaint({
CustomPainter painter,
CustomPainter foregroundPainter,
@@ -1916,18 +1919,18 @@
}
}
-/// Is invisible during hit testing.
+/// A render object that os invisible during hit testing.
///
/// When [ignoring] is `true`, this render object (and its subtree) is invisible
/// to hit testing. It still consumes space during layout and paints its child
-/// as usual. It just cannot be the target of located events because it returns
+/// as usual. It just cannot be the target of located events, because it returns
/// `false` from [hitTest].
///
/// When [ignoringSemantics] is `true`, the subtree will be invisible to
/// the semantics layer (and thus e.g. accessibility tools). If
/// [ignoringSemantics] is null, it uses the value of [ignoring].
class RenderIgnorePointer extends RenderProxyBox {
- /// Creates a render object that is invisivle to hit testing.
+ /// Creates a render object that is invisible to hit testing.
///
/// The [ignoring] argument must not be null. If [ignoringSemantics], this
/// render object will be ignored for semantics if [ignoring] is true.
@@ -1995,8 +1998,13 @@
}
/// Holds opaque meta data in the render tree.
+///
+/// Useful for decorating the render tree with information that will be consumed
+/// later. For example, you could store information in the render tree that will
+/// be used when the user interacts with the render tree but has no visual
+/// impact prior to the interaction.
class RenderMetaData extends RenderProxyBoxWithHitTestBehavior {
- /// Creates a render object that hold opaque metadata.
+ /// Creates a render object that hold opaque meta data.
///
/// The [behavior] argument defaults to [HitTestBehavior.deferToChild].
RenderMetaData({
diff --git a/packages/flutter/lib/src/widgets/basic.dart b/packages/flutter/lib/src/widgets/basic.dart
index f0e1be4..3c2e06f 100644
--- a/packages/flutter/lib/src/widgets/basic.dart
+++ b/packages/flutter/lib/src/widgets/basic.dart
@@ -142,6 +142,9 @@
}
/// Applies a filter to the existing painted content and then paints [child].
+///
+/// This effect is relatively expensive, especially if the filter is non-local,
+/// such as a blur.
class BackdropFilter extends SingleChildRenderObjectWidget {
/// Creates a backdrop filter.
///
@@ -207,12 +210,12 @@
/// Provides a canvas on which to draw during the paint phase.
///
-/// When asked to paint, [CustomPaint] first ask its [painter] to paint on the
+/// When asked to paint, [CustomPaint] first asks its [painter] to paint on the
/// current canvas, then it paints its child, and then, after painting its
-/// child, it ask its [foregroundPainter] to paint. The coodinate system of the
+/// child, it asks its [foregroundPainter] to paint. The coodinate system of the
/// canvas matches the coordinate system of the [CustomPaint] object. The
/// painters are expected to paint within a rectangle starting at the origin and
-/// encompassing a region of the given size. (If the painters paints outside
+/// encompassing a region of the given size. (If the painters paint outside
/// those bounds, there might be insufficient memory allocated to rasterize the
/// painting commands and the resulting behavior is undefined.)
///
@@ -224,10 +227,10 @@
///
/// See also:
///
-/// * [CustomPainter],
+/// * [CustomPainter]
/// * [Canvas]
class CustomPaint extends SingleChildRenderObjectWidget {
- /// Creates a widget that delgates its painting.
+ /// Creates a widget that delegates its painting.
CustomPaint({ Key key, this.painter, this.foregroundPainter, Widget child })
: super(key: key, child: child);
@@ -261,8 +264,8 @@
/// Clips its child using a rectangle.
///
/// By default, [ClipRect] prevents its child from painting outside its
-/// bounds, but the size and location of the clip can be customized using a
-/// custome [clipper].
+/// bounds, but the size and location of the clip rect can be customized using a
+/// custom [clipper].
class ClipRect extends SingleChildRenderObjectWidget {
/// Creates a rectangular clip.
///
@@ -322,9 +325,9 @@
/// Clips its child using an oval.
///
-/// By default, inscribes an oval into its layout dimensions and prevents its
-/// child from painting outside that oval, but the size and location of the clip
-/// can be customized using a custom [clipper].
+/// By default, inscribes an axis-aligned oval into its layout dimensions and
+/// prevents its child from painting outside that oval, but the size and
+/// location of the clip oval can be customized using a custom [clipper].
class ClipOval extends SingleChildRenderObjectWidget {
/// Creates an oval-shaped clip.
///
@@ -665,7 +668,7 @@
}
}
-/// Metadata for identifying children in a [CustomMultiChildLayout].
+/// Meta data for identifying children in a [CustomMultiChildLayout].
/// The [MultiChildLayoutDelegate] hasChild, layoutChild, and positionChild
/// methods use these identifiers.
class LayoutId extends ParentDataWidget<CustomMultiChildLayout> {
@@ -1033,7 +1036,7 @@
/// with the center of the parent.
final FractionalOffset alignment;
- /// The size this render box should attempt to be.
+ /// The size this widget should attempt to be.
final Size size;
@override
@@ -2947,18 +2950,18 @@
RenderRepaintBoundary createRenderObject(BuildContext context) => new RenderRepaintBoundary();
}
-/// Is invisible during hit testing.
+/// A widget that os invisible during hit testing.
///
/// When [ignoring] is `true`, this widget (and its subtree) is invisible
/// to hit testing. It still consumes space during layout and paints its child
-/// as usual. It just cannot be the target of located events because it returns
+/// as usual. It just cannot be the target of located events, because it returns
/// `false` from [hitTest].
///
/// When [ignoringSemantics] is `true`, the subtree will be invisible to
/// the semantics layer (and thus e.g. accessibility tools). If
/// [ignoringSemantics] is null, it uses the value of [ignoring].
class IgnorePointer extends SingleChildRenderObjectWidget {
- /// Creates a widget that is invisivle to hit testing.
+ /// Creates a widget that is invisible to hit testing.
///
/// The [ignoring] argument must not be null. If [ignoringSemantics], this
/// render object will be ignored for semantics if [ignoring] is true.
@@ -2999,8 +3002,13 @@
}
/// Holds opaque meta data in the render tree.
+///
+/// Useful for decorating the render tree with information that will be consumed
+/// later. For example, you could store information in the render tree that will
+/// be used when the user interacts with the render tree but has no visual
+/// impact prior to the interaction.
class MetaData extends SingleChildRenderObjectWidget {
- /// Creates a widget that hold opaque metadata.
+ /// Creates a widget that hold opaque meta data.
///
/// The [behavior] argument defaults to [HitTestBehavior.deferToChild].
MetaData({
diff --git a/packages/flutter/lib/src/widgets/drag_target.dart b/packages/flutter/lib/src/widgets/drag_target.dart
index 4f8d71f..85b7e75 100644
--- a/packages/flutter/lib/src/widgets/drag_target.dart
+++ b/packages/flutter/lib/src/widgets/drag_target.dart
@@ -455,7 +455,7 @@
Iterable<_DragTargetState<T>> _getDragTargets(List<HitTestEntry> path) sync* {
// Look for the RenderBoxes that corresponds to the hit target (the hit target
- // widgets build RenderMetadata boxes for us for this purpose).
+ // widgets build RenderMetaData boxes for us for this purpose).
for (HitTestEntry entry in path) {
if (entry.target is RenderMetaData) {
RenderMetaData renderMetaData = entry.target;
diff --git a/packages/flutter_tools/lib/src/services.dart b/packages/flutter_tools/lib/src/services.dart
index cacee60..c31730f 100644
--- a/packages/flutter_tools/lib/src/services.dart
+++ b/packages/flutter_tools/lib/src/services.dart
@@ -24,7 +24,7 @@
}
/// Loads all services specified in `flutter.yaml`. Parses each service config file,
-/// storing metadata in [services] and the list of jar files in [jars].
+/// storing meta data in [services] and the list of jar files in [jars].
Future<Null> parseServiceConfigs(
List<Map<String, String>> services, { List<File> jars }
) async {
