Fix "unresolved doc reference" in rendering layer (#62443)

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

@@ -1262,12 +1262,12 @@ class _IntrinsicDimensionsCacheEntry {
 /// ### Semantics
 ///
 /// For a render box to be accessible, implement the
-/// [describeApproximatePaintClip] and [visitChildrenForSemantics] methods, and
-/// the [semanticsAnnotator] getter. The default implementations are sufficient
-/// for objects that only affect layout, but nodes that represent interactive
-/// components or information (diagrams, text, images, etc) should provide more
-/// complete implementations. For more information, see the documentation for
-/// these members.
+/// [describeApproximatePaintClip], [visitChildrenForSemantics], and
+/// [describeSemanticsConfiguration] methods. The default implementations are
+/// sufficient for objects that only affect layout, but nodes that represent
+/// interactive components or information (diagrams, text, images, etc) should
+/// provide more complete implementations. For more information, see the
+/// documentation for these members.
 ///
 /// ### Intrinsics and Baselines
 ///
@@ -2199,11 +2199,11 @@ abstract class RenderBox extends RenderObject {
   /// Likewise, this [RenderBox] is responsible for transforming the position
   /// that it passes to its children when it calls [hitTest] on each child.
   ///
-  /// If transforming is necessary, [HitTestResult.addWithPaintTransform],
-  /// [HitTestResult.addWithPaintOffset], or [HitTestResult.addWithRawTransform] need
-  /// to be invoked by subclasses to record the required transform operations
-  /// in the [HitTestResult]. These methods will also help with applying the
-  /// transform to `position`.
+  /// If transforming is necessary, [BoxHitTestResult.addWithPaintTransform],
+  /// [BoxHitTestResult.addWithPaintOffset], or
+  /// [BoxHitTestResult.addWithRawTransform] need to be invoked by subclasses to
+  /// record the required transform operations in the [BoxHitTestResult]. These
+  /// methods will also help with applying the transform to `position`.
   ///
   /// Used by [hitTest]. If you override [hitTest] and do not call this
   /// function, then you don't need to implement this function.

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

@@ -194,9 +194,9 @@ abstract class CustomPainter extends Listenable {
   ///
   /// If the returned function is null, this painter will not contribute new
   /// [SemanticsNode]s to the semantics tree and the [CustomPaint] corresponding
-  /// to this painter will not create a semantics boundary. However, if
-  /// [CustomPaint.child] is not null, the child may contribute [SemanticsNode]s
-  /// to the tree.
+  /// to this painter will not create a semantics boundary. However, if the
+  /// child of a [CustomPaint] is not null, the child may contribute
+  /// [SemanticsNode]s to the tree.
   ///
   /// See also:
   ///

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

@@ -646,7 +646,7 @@ class PlatformViewLayer extends Layer {
 
   /// The unique identifier of the UIView displayed on this layer.
   ///
-  /// A UIView with this identifier must have been created by [PlatformViewsServices.initUiKitView].
+  /// A UIView with this identifier must have been created by [PlatformViewsService.initUiKitView].
   final int viewId;
 
   @override
@@ -1188,7 +1188,7 @@ class OffsetLayer extends ContainerLayer {
   ///
   /// The [pixelRatio] describes the scale between the logical pixels and the
   /// size of the output image. It is independent of the
-  /// [window.devicePixelRatio] for the device, so specifying 1.0 (the default)
+  /// [Window.devicePixelRatio] for the device, so specifying 1.0 (the default)
   /// will give you a 1:1 mapping between logical pixels and the output pixels
   /// in the image.
   ///
@@ -2413,7 +2413,7 @@ class FollowerLayer extends ContainerLayer {
 ///
 /// When an annotation search arrives, this layer defers the same search to each
 /// of this layer's children, respecting their opacity. Then it adds this
-/// layer's [annotation] if all of the following restrictions are met:
+/// layer's annotation if all of the following restrictions are met:
 ///
 /// {@template flutter.rendering.annotatedRegionLayer.restrictions}
 /// * The target type must be identical to the annotated type `T`.

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

@@ -449,7 +449,7 @@ class RenderListWheelViewport
   /// If false, every child will be painted. However the [Scrollable] is still
   /// the size of the viewport and detects gestures inside only.
   ///
-  /// Defaults to [false]. Must not be null. Cannot be true if [clipBehavior]
+  /// Defaults to false. Must not be null. Cannot be true if [clipBehavior]
   /// is not [Clip.none] since children outside the viewport will be clipped, and
   /// therefore cannot render children outside the viewport.
   /// {@endtemplate}

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

@@ -160,7 +160,7 @@ abstract class MouseCursorSession {
 ///
 /// A [MouseCursor] object is used by being assigned to a [MouseRegion] or
 /// another widget that exposes the [MouseRegion] API, such as
-/// [InkWell.mouseCursor].
+/// [InkResponse.mouseCursor].
 ///
 /// {@tool snippet --template=stateless_widget_material}
 /// This sample creates a rectangular region that is wrapped by a [MouseRegion]
@@ -361,7 +361,7 @@ class _SystemMouseCursorSession extends MouseCursorSession {
 ///  * macOS: API name in Objective C
 ///
 /// If the platform that the application is running on is not listed for a cursor,
-/// using this cursor falls back to [basic].
+/// using this cursor falls back to [SystemMouseCursors.basic].
 ///
 /// [SystemMouseCursors] enumerates the complete set of system cursors supported
 /// by Flutter, which are hard-coded in the engine. Therefore, manually
@@ -433,7 +433,8 @@ class SystemMouseCursors {
 
   /// Hide the cursor.
   ///
-  /// Any cursor other than [none] or [uncontrolled] unhides the cursor.
+  /// Any cursor other than [none] or [MouseCursor.uncontrolled] unhides the
+  /// cursor.
   static const SystemMouseCursor none = SystemMouseCursor._(kind: 'none');
 
 

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

@@ -297,8 +297,8 @@ class MouseTrackerUpdateDetails with Diagnosticable {
 ///
 ///   * [MouseTracker], which is a subclass of [BaseMouseTracker] with definition
 ///     of how to process mouse event callbacks and mouse cursors.
-///   * [MouseCursorMixin], which is a mixin for [BaseMouseTracker] that defines
-///     how to process mouse cursors.
+///   * [MouseTrackerCursorMixin], which is a mixin for [BaseMouseTracker] that
+///     defines how to process mouse cursors.
 class BaseMouseTracker extends ChangeNotifier {
   /// Creates a [BaseMouseTracker] to keep track of mouse locations.
   ///

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

@@ -2742,10 +2742,11 @@ abstract class RenderObject extends AbstractNode with DiagnosticableTreeMixin im
 
   /// Assemble the [SemanticsNode] for this [RenderObject].
   ///
-  /// If [isSemanticBoundary] is true, this method is called with the `node`
-  /// created for this [RenderObject], the `config` to be applied to that node
-  /// and the `children` [SemanticsNode]s that descendants of this RenderObject
-  /// have generated.
+  /// If [describeSemanticsConfiguration] sets
+  /// [SemanticsConfiguration.isSemanticBoundary] to true, this method is called
+  /// with the `node` created for this [RenderObject], the `config` to be
+  /// applied to that node and the `children` [SemanticsNode]s that descendants
+  /// of this RenderObject have generated.
   ///
   /// By default, the method will annotate `node` with `config` and add the
   /// `children` to it.

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

@@ -68,7 +68,7 @@ Set<Type> _factoriesTypeSet<T>(Set<Factory<T>> factories) {
 /// {@endtemplate}
 ///
 /// {@template flutter.rendering.platformView.gestures}
-/// The render object participates in Flutter's [GestureArena]s, and dispatches touch events to the
+/// The render object participates in Flutter's gesture arenas, and dispatches touch events to the
 /// platform view iff it won the arena. Specific gestures that should be dispatched to the platform
 /// view can be specified with factories in the `gestureRecognizers` constructor parameter or
 /// by calling `updateGestureRecognizers`. If the set of gesture recognizers is empty, the gesture

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

@@ -1882,7 +1882,7 @@ class RenderPhysicalModel extends _RenderPhysicalModelBase<RRect> {
 class RenderPhysicalShape extends _RenderPhysicalModelBase<Path> {
   /// Creates an arbitrary shape clip.
   ///
-  /// The [color] and [shape] parameters are required.
+  /// The [color] and [clipper] parameters are required.
   ///
   /// The [clipper], [elevation], [color] and [shadowColor] must not be null.
   /// Additionally, the [elevation] must be non-negative.
@@ -2149,10 +2149,10 @@ class RenderTransform extends RenderProxyBox {
   /// This is equivalent to setting an origin based on the size of the box.
   /// If it is specified at the same time as an offset, both are applied.
   ///
-  /// An [AlignmentDirectional.start] value is the same as an [Alignment]
+  /// An [AlignmentDirectional.centerStart] value is the same as an [Alignment]
   /// whose [Alignment.x] value is `-1.0` if [textDirection] is
   /// [TextDirection.ltr], and `1.0` if [textDirection] is [TextDirection.rtl].
-  /// Similarly [AlignmentDirectional.end] is the same as an [Alignment]
+  /// Similarly [AlignmentDirectional.centerEnd] is the same as an [Alignment]
   /// whose [Alignment.x] value is `1.0` if [textDirection] is
   /// [TextDirection.ltr], and `-1.0` if [textDirection] is [TextDirection.rtl].
   AlignmentGeometry get alignment => _alignment;
@@ -2947,7 +2947,7 @@ class RenderRepaintBoundary extends RenderProxyBox {
   ///
   /// The [pixelRatio] describes the scale between the logical pixels and the
   /// size of the output image. It is independent of the
-  /// [window.devicePixelRatio] for the device, so specifying 1.0 (the default)
+  /// [Window.devicePixelRatio] for the device, so specifying 1.0 (the default)
   /// will give you a 1:1 mapping between logical pixels and the output pixels
   /// in the image.
   ///
@@ -3807,7 +3807,8 @@ class RenderSemanticsAnnotations extends RenderProxyBox {
     markNeedsSemanticsUpdate();
   }
 
-  /// If non-null, sets the [SemanticsNode.isLink] semantic to the given value.
+  /// If non-null, sets the [SemanticsConfiguration.isLink] semantic to the
+  /// given value.
   bool get link => _link;
   bool _link;
   set link(bool value) {
@@ -3817,7 +3818,8 @@ class RenderSemanticsAnnotations extends RenderProxyBox {
     markNeedsSemanticsUpdate();
   }
 
-  /// If non-null, sets the [SemanticsNode.isHeader] semantic to the given value.
+  /// If non-null, sets the [SemanticsConfiguration.isHeader] semantic to the
+  /// given value.
   bool get header => _header;
   bool _header;
   set header(bool value) {
@@ -3827,7 +3829,8 @@ class RenderSemanticsAnnotations extends RenderProxyBox {
     markNeedsSemanticsUpdate();
   }
 
-  /// If non-null, sets the [SemanticsNode.isTextField] semantic to the given value.
+  /// If non-null, sets the [SemanticsConfiguration.isTextField] semantic to the
+  /// given value.
   bool get textField => _textField;
   bool _textField;
   set textField(bool value) {
@@ -3837,7 +3840,8 @@ class RenderSemanticsAnnotations extends RenderProxyBox {
     markNeedsSemanticsUpdate();
   }
 
-  /// If non-null, sets the [SemanticsNode.isReadOnly] semantic to the given value.
+  /// If non-null, sets the [SemanticsConfiguration.isReadOnly] semantic to the
+  /// given value.
   bool get readOnly => _readOnly;
   bool _readOnly;
   set readOnly(bool value) {
@@ -3847,7 +3851,8 @@ class RenderSemanticsAnnotations extends RenderProxyBox {
     markNeedsSemanticsUpdate();
   }
 
-  /// If non-null, sets the [SemanticsNode.isFocusable] semantic to the given value.
+  /// If non-null, sets the [SemanticsConfiguration.isFocusable] semantic to the
+  /// given value.
   bool get focusable => _focusable;
   bool _focusable;
   set focusable(bool value) {
@@ -3857,7 +3862,8 @@ class RenderSemanticsAnnotations extends RenderProxyBox {
     markNeedsSemanticsUpdate();
   }
 
-  /// If non-null, sets the [SemanticsNode.isFocused] semantic to the given value.
+  /// If non-null, sets the [SemanticsConfiguration.isFocused] semantic to the
+  /// given value.
   bool get focused => _focused;
   bool _focused;
   set focused(bool value) {
@@ -3867,8 +3873,8 @@ class RenderSemanticsAnnotations extends RenderProxyBox {
     markNeedsSemanticsUpdate();
   }
 
-  /// If non-null, sets the [SemanticsNode.isInMutuallyExclusiveGroup] semantic
-  /// to the given value.
+  /// If non-null, sets the [SemanticsConfiguration.isInMutuallyExclusiveGroup]
+  /// semantic to the given value.
   bool get inMutuallyExclusiveGroup => _inMutuallyExclusiveGroup;
   bool _inMutuallyExclusiveGroup;
   set inMutuallyExclusiveGroup(bool value) {
@@ -3878,8 +3884,8 @@ class RenderSemanticsAnnotations extends RenderProxyBox {
     markNeedsSemanticsUpdate();
   }
 
-  /// If non-null, sets the [SemanticsNode.isObscured] semantic to the given
-  /// value.
+  /// If non-null, sets the [SemanticsConfiguration.isObscured] semantic to the
+  /// given value.
   bool get obscured => _obscured;
   bool _obscured;
   set obscured(bool value) {
@@ -3900,7 +3906,8 @@ class RenderSemanticsAnnotations extends RenderProxyBox {
     markNeedsSemanticsUpdate();
   }
 
-  /// If non-null, sets the [SemanticsNode.scopesRoute] semantic to the give value.
+  /// If non-null, sets the [SemanticsConfiguration.scopesRoute] semantic to the
+  /// give value.
   bool get scopesRoute => _scopesRoute;
   bool _scopesRoute;
   set scopesRoute(bool value) {
@@ -3910,7 +3917,8 @@ class RenderSemanticsAnnotations extends RenderProxyBox {
     markNeedsSemanticsUpdate();
   }
 
-  /// If non-null, sets the [SemanticsNode.namesRoute] semantic to the give value.
+  /// If non-null, sets the [SemanticsConfiguration.namesRoute] semantic to the
+  /// give value.
   bool get namesRoute => _namesRoute;
   bool _namesRoute;
   set namesRoute(bool value) {
@@ -3920,8 +3928,8 @@ class RenderSemanticsAnnotations extends RenderProxyBox {
     markNeedsSemanticsUpdate();
   }
 
-  /// If non-null, sets the [SemanticsNode.isHidden] semantic to the given
-  /// value.
+  /// If non-null, sets the [SemanticsConfiguration.isHidden] semantic to the
+  /// given value.
   bool get hidden => _hidden;
   bool _hidden;
   set hidden(bool value) {
@@ -3931,8 +3939,8 @@ class RenderSemanticsAnnotations extends RenderProxyBox {
     markNeedsSemanticsUpdate();
   }
 
-  /// If non-null, sets the [SemanticsNode.isImage] semantic to the given
-  /// value.
+  /// If non-null, sets the [SemanticsConfiguration.isImage] semantic to the
+  /// given value.
   bool get image => _image;
   bool _image;
   set image(bool value) {
@@ -3941,8 +3949,8 @@ class RenderSemanticsAnnotations extends RenderProxyBox {
     _image = value;
   }
 
-  /// If non-null, sets the [SemanticsFlag.isLiveRegion] semantic to the given
-  /// value.
+  /// If non-null, sets the [SemanticsConfiguration.liveRegion] semantic to
+  /// the given value.
   bool get liveRegion => _liveRegion;
   bool _liveRegion;
   set liveRegion(bool value) {
@@ -3974,7 +3982,7 @@ class RenderSemanticsAnnotations extends RenderProxyBox {
     markNeedsSemanticsUpdate();
   }
 
-  /// If non-null, sets the [SemanticsNode.isToggled] semantic to the given
+  /// If non-null, sets the [SemanticsConfiguration.isToggled] semantic to the given
   /// value.
   bool get toggled => _toggled;
   bool _toggled;
@@ -4047,7 +4055,7 @@ class RenderSemanticsAnnotations extends RenderProxyBox {
     markNeedsSemanticsUpdate();
   }
 
-  /// If non-null, sets the [SemanticsNode.hintOverride] to the given value.
+  /// If non-null, sets the [SemanticsConfiguration.hintOverrides] to the given value.
   SemanticsHintOverrides get hintOverrides => _hintOverrides;
   SemanticsHintOverrides _hintOverrides;
   set hintOverrides(SemanticsHintOverrides value) {
@@ -4318,7 +4326,7 @@ class RenderSemanticsAnnotations extends RenderProxyBox {
       markNeedsSemanticsUpdate();
   }
 
-  /// The handler for [SemanticsAction.onMoveCursorForwardByCharacter].
+  /// The handler for [SemanticsAction.moveCursorForwardByCharacter].
   ///
   /// This handler is invoked when the user wants to move the cursor in a
   /// text field forward by one character.
@@ -4336,7 +4344,7 @@ class RenderSemanticsAnnotations extends RenderProxyBox {
       markNeedsSemanticsUpdate();
   }
 
-  /// The handler for [SemanticsAction.onMoveCursorBackwardByCharacter].
+  /// The handler for [SemanticsAction.moveCursorBackwardByCharacter].
   ///
   /// This handler is invoked when the user wants to move the cursor in a
   /// text field backward by one character.
@@ -4354,7 +4362,7 @@ class RenderSemanticsAnnotations extends RenderProxyBox {
       markNeedsSemanticsUpdate();
   }
 
-  /// The handler for [SemanticsAction.onMoveCursorForwardByWord].
+  /// The handler for [SemanticsAction.moveCursorForwardByWord].
   ///
   /// This handler is invoked when the user wants to move the cursor in a
   /// text field backward by one character.
@@ -4372,7 +4380,7 @@ class RenderSemanticsAnnotations extends RenderProxyBox {
       markNeedsSemanticsUpdate();
   }
 
-  /// The handler for [SemanticsAction.onMoveCursorBackwardByWord].
+  /// The handler for [SemanticsAction.moveCursorBackwardByWord].
   ///
   /// This handler is invoked when the user wants to move the cursor in a
   /// text field backward by one character.
@@ -5079,7 +5087,7 @@ class RenderAnnotatedRegion<T> extends RenderProxyBox {
   /// layer tree.
   ///
   /// If [sized] is true, the layer is provided with the size of this render
-  /// object to clip the results of [Layer.findRegion].
+  /// object to clip the results of [Layer.find].
   ///
   /// Neither [value] nor [sized] can be null.
   RenderAnnotatedRegion({

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

@@ -227,27 +227,27 @@ class SliverConstraints extends Constraints {
   /// contents depends on the [growthDirection].
   final double scrollOffset;
 
-  /// The scroll distance that has been consumed by all [Sliver]s that came
-  /// before this [Sliver].
+  /// The scroll distance that has been consumed by all [RenderSliver]s that
+  /// came before this [RenderSliver].
   ///
   /// # Edge Cases
   ///
-  /// [Sliver]s often lazily create their internal content as layout occurs,
-  /// e.g., [SliverList]. In this case, when [Sliver]s exceed the viewport,
-  /// their children are built lazily, and the [Sliver] does not have enough
-  /// information to estimate its total extent, [precedingScrollExtent] will be
-  /// [double.infinity] for all [Sliver]s that appear after the lazily
-  /// constructed child. This is because a total [scrollExtent] cannot be
-  /// calculated unless all inner children have been created and sized, or the
-  /// number of children and estimated extents are provided. The infinite
-  /// [scrollExtent] will become finite as soon as enough information is
-  /// available to estimate the overall extent of all children within the given
-  /// [Sliver].
-  ///
-  /// [Sliver]s may legitimately be infinite, meaning that they can scroll
-  /// content forever without reaching the end. For any [Sliver]s that appear
-  /// after the infinite [Sliver], the [precedingScrollExtent] will be
-  /// [double.infinity].
+  /// [RenderSliver]s often lazily create their internal content as layout
+  /// occurs, e.g., [SliverList]. In this case, when [RenderSliver]s exceed the
+  /// viewport, their children are built lazily, and the [RenderSliver] does not
+  /// have enough information to estimate its total extent,
+  /// [precedingScrollExtent] will be [double.infinity] for all [RenderSliver]s
+  /// that appear after the lazily constructed child. This is because a total
+  /// [SliverGeometry.scrollExtent] cannot be calculated unless all inner
+  /// children have been created and sized, or the number of children and
+  /// estimated extents are provided. The infinite [SliverGeometry.scrollExtent]
+  /// will become finite as soon as enough information is available to estimate
+  /// the overall extent of all children within the given [RenderSliver].
+  ///
+  /// [RenderSliver]s may legitimately be infinite, meaning that they can scroll
+  /// content forever without reaching the end. For any [RenderSliver]s that
+  /// appear after the infinite [RenderSliver], the [precedingScrollExtent] will
+  /// be [double.infinity].
   final double precedingScrollExtent;
 
   /// The number of pixels from where the pixels corresponding to the
@@ -788,7 +788,7 @@ class SliverGeometry with Diagnosticable {
   }
 }
 
-/// Method signature for hit testing a [RenderSLiver].
+/// Method signature for hit testing a [RenderSliver].
 ///
 /// Used by [SliverHitTestResult.addWithAxisOffset] to hit test [RenderSliver]
 /// children.

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

@@ -44,10 +44,6 @@ abstract class RenderSliverBoxChildManager {
   /// the [RenderSliverMultiBoxAdaptor] object if they were not created during
   /// this frame and have not yet been updated during this frame. It is not
   /// valid to add any other children to this render object.
-  ///
-  /// If this method does not create a child for a given `index` greater than or
-  /// equal to zero, then [computeMaxScrollOffset] must be able to return a
-  /// precise value.
   void createChild(int index, { @required RenderBox after });
 
   /// Remove the given child from the child list.

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

@@ -301,7 +301,7 @@ abstract class RenderViewportBase<ParentDataClass extends ContainerParentDataMix
   /// {@template flutter.rendering.viewport.cacheExtentStyle}
   /// Controls how the [cacheExtent] is interpreted.
   ///
-  /// If set to [CacheExtentStyle.pixels], the [cacheExtent] will be treated as
+  /// If set to [CacheExtentStyle.pixel], the [cacheExtent] will be treated as
   /// a logical pixels.
   ///
   /// If set to [CacheExtentStyle.viewport], the [cacheExtent] will be treated
@@ -1232,7 +1232,7 @@ class RenderViewport extends RenderViewportBase<SliverPhysicalContainerParentDat
   /// The first child in the [GrowthDirection.forward] growth direction.
   ///
   /// This child that will be at the position defined by [anchor] when the
-  /// [offset.pixels] is `0`.
+  /// [ViewportOffset.pixels] of [offset] is `0`.
   ///
   /// Children after [center] will be placed in the [axisDirection] relative to
   /// the [center]. Children before [center] will be placed in the opposite of

packages/flutter/lib/src/services/restoration.dart

@@ -40,7 +40,7 @@ typedef _BucketVisitor = void Function(RestorationBucket bucket);
 /// [rootBucket] provided by this [RestorationManager]). The owner of a bucket
 /// may store arbitrary values in the bucket as long as they can be serialized
 /// with the [StandardMessageCodec]. The values are stored in the bucket under a
-/// given restoration ID as key. A restoration ID is a [Sting] that must be
+/// given restoration ID as key. A restoration ID is a [String] that must be
 /// unique within a given bucket. To access the stored value again during state
 /// restoration, the same restoration ID must be provided again. The owner of
 /// the bucket may also make the bucket available to other entities so that they
@@ -458,7 +458,7 @@ class RestorationBucket extends ChangeNotifier {
   }
 
   /// Creates a child bucket initialized with the data that the provided
-  /// `parent` has stored under the provided [id].
+  /// `parent` has stored under the provided [restorationId].
   ///
   /// This constructor cannot be used if the `parent` does not have any child
   /// data stored under the given ID. In that case, create an empty bucket (via
@@ -720,9 +720,9 @@ class RestorationBucket extends ChangeNotifier {
   ///
   /// The `child` will be dropped from its old parent, if it had one.
   ///
-  /// The `child` is stored under its [id] in this bucket. If this bucket
-  /// already contains a child bucket under the same id, the owner of that
-  /// existing bucket must give it up (e.g. by moving the child bucket to a
+  /// The `child` is stored under its [restorationId] in this bucket. If this
+  /// bucket already contains a child bucket under the same id, the owner of
+  /// that existing bucket must give it up (e.g. by moving the child bucket to a
   /// different parent or by disposing it) before the end of the current frame.
   /// Otherwise an exception indicating the illegal use of duplicated
   /// restoration IDs will trigger in debug mode.