Updating example for MultiChildLayoutDelegate (#15597)

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

@@ -41,26 +41,43 @@ class MultiChildLayoutParentData extends ContainerBoxParentData<RenderBox> {
 /// Used with [CustomMultiChildLayout], the widget for the
 /// [RenderCustomMultiChildLayoutBox] render object.
 ///
-/// ## Example
+/// Each child must be wrapped in a [LayoutId] widget to assign the id that
+/// identifies it to the delegate. The [LayoutId.id] needs to be unique among
+/// the children that the [CustomMultiChildLayout] manages.
+///
+/// ## Sample code
 ///
 /// Below is an example implementation of [performLayout] that causes one widget
-/// to be the same size as another:
+/// (the follower) to be the same size as another (the leader):
 ///
 /// ```dart
-/// @override
-/// void performLayout(Size size) {
-///   Size followerSize = Size.zero;
-///
-///   if (hasChild(_Slots.leader) {
-///     followerSize = layoutChild(_Slots.leader, new BoxConstraints.loose(size));
-///     positionChild(_Slots.leader, Offset.zero);
-///   }
-///
-///   if (hasChild(_Slots.follower)) {
-///     layoutChild(_Slots.follower, new BoxConstraints.tight(followerSize));
-///     positionChild(_Slots.follower, new Offset(size.width - followerSize.width,
-///                                               size.height - followerSize.height));
+/// // Define your own slot numbers, depending upon the id assigned by LayoutId.
+/// // Typical usage is to define an enum like the one below, and use those
+/// // values as the ids.
+/// enum _Slot {
+///   leader,
+///   follower,
+/// }
+/// 
+/// class FollowTheLeader extends MultiChildLayoutDelegate {
+///   @override
+///   void performLayout(Size size) {
+///     Size leaderSize = Size.zero;
+/// 
+///     if (hasChild(_Slot.leader)) {
+///       leaderSize = layoutChild(_Slot.leader, new BoxConstraints.loose(size));
+///       positionChild(_Slot.leader, Offset.zero);
+///     }
+/// 
+///     if (hasChild(_Slot.follower)) {
+///       layoutChild(_Slot.follower, new BoxConstraints.tight(leaderSize));
+///       positionChild(_Slot.follower, new Offset(size.width - leaderSize.width,
+///           size.height - leaderSize.height));
+///     }
 ///   }
+/// 
+///   @override
+///   bool shouldRelayout(MultiChildLayoutDelegate oldDelegate) => false;
 /// }
 /// ```
 ///

packages/flutter/lib/src/widgets/basic.dart

@@ -1448,7 +1448,7 @@ class CustomSingleChildLayout extends SingleChildRenderObjectWidget {
   }
 }
 
-/// Meta data for identifying children in a [CustomMultiChildLayout].
+/// Metadata for identifying children in a [CustomMultiChildLayout].
 ///
 /// The [MultiChildLayoutDelegate.hasChild],
 /// [MultiChildLayoutDelegate.layoutChild], and
@@ -1466,6 +1466,9 @@ class LayoutId extends ParentDataWidget<CustomMultiChildLayout> {
        super(key: key ?? new ValueKey<Object>(id), child: child);
 
   /// An object representing the identity of this child.
+  ///
+  /// The [id] needs to be unique among the children that the
+  /// [CustomMultiChildLayout] manages.
   final Object id;
 
   @override

packages/flutter/lib/src/widgets/framework.dart

@@ -4462,13 +4462,17 @@ abstract class RenderObjectElement extends Element {
   @override
   void deactivate() {
     super.deactivate();
-    assert(!renderObject.attached);
+    assert(!renderObject.attached,
+      'A RenderObject was still attached when attempting to deactivate its '
+      'RenderObjectElement: $renderObject');
   }
 
   @override
   void unmount() {
     super.unmount();
-    assert(!renderObject.attached);
+    assert(!renderObject.attached,
+      'A RenderObject was still attached when attempting to unmount its '
+      'RenderObjectElement: $renderObject');
     widget.didUnmountRenderObject(renderObject);
   }