Improve Documentation for ResizeImage Dimensions and Usage (#154212)

This pull request enhances the documentation for the ResizeImage widget to provide clearer guidance on the use of the `width` and `height` parameters.

Fixes #136508

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

@@ -2,6 +2,9 @@
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
+// Examples can assume:
+// late BuildContext context;
+
 /// @docImport 'package:flutter/widgets.dart';
 library;
 
@@ -1191,11 +1194,31 @@ enum ResizeImagePolicy {
 /// Instructs Flutter to decode the image at the specified dimensions
 /// instead of at its native size.
 ///
+/// The [width] and [height] parameters refer to logical pixels.
+///
+/// Logical pixels have roughly the same visual size across devices, whereas
+/// physical pixels correspond to actual device hardware.
+/// The number of physical pixels per logical pixel is described by the
+/// [ui.FlutterView.devicePixelRatio].
+///
 /// This allows finer control of the size of the image in [ImageCache] and is
 /// generally used to reduce the memory footprint of [ImageCache].
 ///
 /// The decoded image may still be displayed at sizes other than the
 /// cached size provided here.
+///
+/// {@tool snippet}
+/// This example shows how to size the image to half of the screen's width.
+///
+/// ```dart
+///    Image(
+///      image: ResizeImage(
+///        FileImage(File('path/to/image')),
+///        width: MediaQuery.sizeOf(context).width ~/ 2, // Half of the screen's width.
+///      ),
+///    );
+/// ```
+/// {@end-tool}
 class ResizeImage extends ImageProvider<ResizeImageKey> {
   /// Creates an ImageProvider that decodes the image to the specified size.
   ///