From 7eb07c983c5c2747d8b3efbd110d486c9ae7fdb9 Mon Sep 17 00:00:00 2001
From: RamonFarizel <45459898+RamonFarizel@users.noreply.github.com>
Date: Tue, 3 Sep 2024 19:18:21 -0300
Subject: [PATCH] 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
---
 .../lib/src/painting/image_provider.dart      | 23 +++++++++++++++++++
 1 file changed, 23 insertions(+)

diff --git a/packages/flutter/lib/src/painting/image_provider.dart b/packages/flutter/lib/src/painting/image_provider.dart
index bdf23e0740..ae9d833d81 100644
--- a/packages/flutter/lib/src/painting/image_provider.dart
+++ b/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.
   ///