Repository: flutter
Issue: Clarify ImagePicker.getImage() maxWidth and imageQuality args docs
Labels: d: api docs,a: quality,p: image_picker,package,team-ecosystem,P3,triaged-ecosystem

## Use case

The docs on[`ImagePicker.getImage()`](https://pub.dev/documentation/image_picker/latest/image_picker/ImagePicker/getImage.html) state:
> If specified, the image will be at most `maxWidth` wide and `maxHeight` tall. Otherwise the image will be returned at it's original width and height. The `imageQuality` argument modifies the quality of the image, ranging from 0-100 where 100 is the original/max quality. If `imageQuality` is null, the image with the original quality will be returned. Compression is only supported for certain image types such as JPEG and on Android PNG and WebP, too. If compression is not supported for the image that is picked, a warning message will be logged.

For the camera mode, these settings have a reasonable expected interpretation: tell the camera the max resolution and compression level for the new file.  For retrieving an existing photo, the `maxWidth` and `maxHeight` could mean either "don't let the user select a photo larger than this" or "resize the photo if it is larger than this".  Similarly, `imageQuality` could mean "always reduce the quality of the image by this amount" or "reduce the image quality to this level if it is higher than this level".  To find out the answer, one has to waste time looking at the source code.

## Proposal

Clearly state what `getImage` does when passed the `maxWidth` and `maxHeight` args.  Use active voice (<https://developers.google.com/tech-writing/one/active-voice>).  Example:

> When `imageSource` is `ImageSource.gallery`:
> - When `maxWidth` and `maxHeight` are non-null, checks the size of the selected image.  If its width is larger than `maxWidth` or its height is larger than `maxHeight`, resizes it to meet those requirements.  Preserves aspect ratio.  Compresses the new image at level `imageQuality`.
> - When `imageQuality` is non-null and the selected file has an image quality that is higher than `imageQuality`, re-encodes the image so its image quality level is `imageQuality`.  Writes the resulting image to a new file of the same type.  Does nothing if the file format does not support lossy compression.
>   - Example: When `imageQuality=95` and the user selects a file `image1.jpg` that was encoded at quality 90, returns the file unchanged.
>   - Example: When `imageQuality=75` and the user selects a file `image1.jpg` that was encoded at quality 90, re-encodes the image at quality 75 and writes it to a new file.
> 
> When `imageSource` is `ImageSource.camera`:
> - When `maxWidth` and `maxHeight` are non-null, asks the camera to take the photo at that resolution.  If the camera returns a photo whose width is larger than `maxWidth` or its height is larger than `maxHeight`, resizes it to meet those requirements.  Preserves aspect ratio.
> - When `imageQuality` is non-null, asks the camera to encode the image at that quality level.  If the camera returns a photo with a higher quality level, re-encodes the image so its image quality level is `imageQuality`.

Related: #82738