Improved AssetImage Docs (#78173)

packages/flutter/lib/src/painting/image_resolution.dart

@@ -117,6 +117,86 @@ const double _kLowDprLimit = 2.0;
 /// AssetImage('icons/heart.png')
 /// ```
 ///
+/// {@tool snippet}
+///
+/// The following shows the code required to write a widget that fully conforms
+/// to the [AssetImage] and [Widget] protocols. (It is essentially a
+/// bare-bones version of the [widgets.Image] widget made to work specifically for
+/// an [AssetImage].)
+///
+/// ```dart
+/// class MyImage extends StatefulWidget {
+///   const MyImage({
+///     Key? key,
+///     required this.assetImage,
+///   }) : super(key: key);
+///
+///   final AssetImage assetImage;
+///
+///   @override
+///   State<MyImage> createState() => _MyImageState();
+/// }
+///
+/// class _MyImageState extends State<MyImage> {
+///   ImageStream? _imageStream;
+///   ImageInfo? _imageInfo;
+///
+///   @override
+///   void didChangeDependencies() {
+///     super.didChangeDependencies();
+///     // We call _getImage here because createLocalImageConfiguration() needs to
+///     // be called again if the dependencies changed, in case the changes relate
+///     // to the DefaultAssetBundle, MediaQuery, etc, which that method uses.
+///     _getImage();
+///   }
+///
+///   @override
+///   void didUpdateWidget(MyImage oldWidget) {
+///     super.didUpdateWidget(oldWidget);
+///     if (widget.assetImage != oldWidget.assetImage)
+///       _getImage();
+///   }
+///
+///   void _getImage() {
+///     final ImageStream? oldImageStream = _imageStream;
+///     _imageStream = widget.assetImage.resolve(createLocalImageConfiguration(context));
+///     if (_imageStream!.key != oldImageStream?.key) {
+///       // If the keys are the same, then we got the same image back, and so we don't
+///       // need to update the listeners. If the key changed, though, we must make sure
+///       // to switch our listeners to the new image stream.
+///       final ImageStreamListener listener = ImageStreamListener(_updateImage);
+///       oldImageStream?.removeListener(listener);
+///       _imageStream!.addListener(listener);
+///     }
+///   }
+///
+///   void _updateImage(ImageInfo imageInfo, bool synchronousCall) {
+///     setState(() {
+///       // Trigger a build whenever the image changes.
+///       _imageInfo?.dispose();
+///       _imageInfo = imageInfo;
+///     });
+///   }
+///
+///   @override
+///   void dispose() {
+///     _imageStream?.removeListener(ImageStreamListener(_updateImage));
+///     _imageInfo?.dispose();
+///     _imageInfo = null;
+///     super.dispose();
+///   }
+///
+///   @override
+///   Widget build(BuildContext context) {
+///     return RawImage(
+///       image: _imageInfo?.image, // this is a dart:ui Image object
+///       scale: _imageInfo?.scale ?? 1.0,
+///     );
+///   }
+/// }
+/// ```
+/// {@end-tool}
+///
 /// ## Assets in packages
 ///
 /// To fetch an asset from a package, the [package] argument must be provided.