[ReorderableListView] Update doc with example to make it clear proxyDecorator can overriden to customise an item when it is being dragged. (#91837)

examples/api/lib/material/reorderable_list/reorderable_list_view.0.dart

@@ -44,7 +44,7 @@ class _MyStatefulWidgetState extends State<MyStatefulWidget> {
     return ReorderableListView(
       padding: const EdgeInsets.symmetric(horizontal: 40),
       children: <Widget>[
-        for (int index = 0; index < _items.length; index++)
+        for (int index = 0; index < _items.length; index += 1)
           ListTile(
             key: Key('$index'),
             tileColor: _items[index].isOdd ? oddItemColor : evenItemColor,

examples/api/lib/material/reorderable_list/reorderable_list_view.1.dart

@@ -0,0 +1,85 @@
+// Copyright 2014 The Flutter Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+// Flutter code sample for ReorderableListView
+import 'dart:ui';
+
+import 'package:flutter/material.dart';
+
+void main() => runApp(const MyApp());
+
+class MyApp extends StatelessWidget {
+  const MyApp({Key? key}) : super(key: key);
+
+  static const String _title = 'Flutter Code Sample';
+
+  @override
+  Widget build(BuildContext context) {
+    return MaterialApp(
+      title: _title,
+      home: Scaffold(
+        appBar: AppBar(title: const Text(_title)),
+        body: const MyStatefulWidget(),
+      ),
+    );
+  }
+}
+
+class MyStatefulWidget extends StatefulWidget {
+  const MyStatefulWidget({Key? key}) : super(key: key);
+
+  @override
+  State<MyStatefulWidget> createState() => _MyStatefulWidgetState();
+}
+
+class _MyStatefulWidgetState extends State<MyStatefulWidget> {
+  final List<int> _items = List<int>.generate(50, (int index) => index);
+
+  @override
+  Widget build(BuildContext context) {
+    final ColorScheme colorScheme = Theme.of(context).colorScheme;
+    final Color oddItemColor = colorScheme.primary.withOpacity(0.05);
+    final Color evenItemColor = colorScheme.primaryVariant.withOpacity(0.15);
+    final Color draggableItemColor = colorScheme.secondary;
+
+    Widget _proxyDecorator(Widget child, int index, Animation<double> animation) {
+      return AnimatedBuilder(
+        animation: animation,
+        builder: (BuildContext context, Widget? child) {
+          final double animValue = Curves.easeInOut.transform(animation.value);
+          final double elevation = lerpDouble(0, 6, animValue)!;
+          return Material(
+            elevation: elevation,
+            color: draggableItemColor,
+            shadowColor: draggableItemColor,
+            child: child,
+          );
+        },
+        child: child,
+      );
+    }
+
+    return ReorderableListView(
+      padding: const EdgeInsets.symmetric(horizontal: 40),
+      proxyDecorator: _proxyDecorator,
+      children: <Widget>[
+        for (int index = 0; index < _items.length; index += 1)
+          ListTile(
+            key: Key('$index'),
+            tileColor: _items[index].isOdd ? oddItemColor : evenItemColor,
+            title: Text('Item ${_items[index]}'),
+          ),
+      ],
+      onReorder: (int oldIndex, int newIndex) {
+        setState(() {
+          if (oldIndex < newIndex) {
+            newIndex -= 1;
+          }
+          final int item = _items.removeAt(oldIndex);
+          _items.insert(newIndex, item);
+        });
+      },
+    );
+  }
+}

packages/flutter/lib/src/material/reorderable_list.dart

@@ -31,9 +31,19 @@ import 'theme.dart';
 ///
 /// {@tool dartpad}
 ///
-///
 /// ** See code in examples/api/lib/material/reorderable_list/reorderable_list_view.0.dart **
-///{@end-tool}
+/// {@end-tool}
+///
+/// This example demonstrates using the [proxyDecorator] callback to customize the appearance of
+/// a list item while it's being dragged.
+/// {@tool snippet}
+///
+/// While a drag is underway, the widget returned by the [proxyDecorator] serves as a "proxy" (a substitute)
+/// for the item in the list. The proxy is created with the original list item as its child. The [proxyDecorator]
+/// in this example is similar to the default one except that it changes the proxy item's background color.
+///
+/// ** See code in examples/api/lib/material/reorderable_list/reorderable_list_view.1.dart **
+/// {@end-tool}
 class ReorderableListView extends StatefulWidget {
   /// Creates a reorderable list from a pre-built list of widgets.
   ///