[image_picker_for_web] Add doc comments to point out that some arguments aren't supported on the web (flutter#3566)

ditman · devj3ns · Chris Yang · web-flow · commit e8b38f6e03d1 · 2021-02-19T11:13:29.000-08:00
Re-landing a PR that @ditman messed up! flutter#3566 Co-authored-by: Jens Becker <jensbecker01@gmx.de> Co-authored-by: Chris Yang <ychris@google.com>
diff --git a/packages/image_picker/image_picker_for_web/CHANGELOG.md b/packages/image_picker/image_picker_for_web/CHANGELOG.md
@@ -1,3 +1,7 @@
+# 2.0.0-nullsafety.1
+
+* Add doc comments to point out that some arguments aren't supported on the web.
+
 # 2.0.0-nullsafety
 
 * Migrate to null safety.
diff --git a/packages/image_picker/image_picker_for_web/README.md b/packages/image_picker/image_picker_for_web/README.md
@@ -2,7 +2,7 @@
 
 A web implementation of [`image_picker`][1].
 
-## Browser Support
+## Limitations on the web platform
 
 Since Web Browsers don't offer direct access to their users' file system,
 this plugin provides a `PickedFile` abstraction to make access access uniform
@@ -42,6 +42,12 @@ In order to "take a photo", some mobile browsers offer a [`capture` attribute](h
 Each browser may implement `capture` any way they please, so it may (or may not) make a
 difference in your users' experience.
 
+### pickImage()
+The arguments `maxWidth`, `maxHeight` and `imageQuality` are not supported on the web.
+
+### pickVideo()
+The argument `maxDuration` is not supported on the web.
+
 ## Usage
 
 ### Import the package
diff --git a/packages/image_picker/image_picker_for_web/lib/image_picker_for_web.dart b/packages/image_picker/image_picker_for_web/lib/image_picker_for_web.dart
@@ -30,6 +30,18 @@ class ImagePickerPlugin extends ImagePickerPlatform {
     ImagePickerPlatform.instance = ImagePickerPlugin();
   }
 
+  /// Returns a [PickedFile] with the image that was picked.
+  ///
+  /// The `source` argument controls where the image comes from. This can
+  /// be either [ImageSource.camera] or [ImageSource.gallery].
+  ///
+  /// Note that the `maxWidth`, `maxHeight` and `imageQuality` arguments are not supported on the web. If any of these arguments is supplied, it'll be silently ignored by the web version of the plugin.
+  ///
+  /// Use `preferredCameraDevice` to specify the camera to use when the `source` is [ImageSource.camera].
+  /// The `preferredCameraDevice` is ignored when `source` is [ImageSource.gallery]. It is also ignored if the chosen camera is not supported on the device.
+  /// Defaults to [CameraDevice.rear].
+  ///
+  /// If no images were picked, the return value is null.
   @override
   Future<PickedFile> pickImage({
     required ImageSource source,
@@ -42,6 +54,18 @@ class ImagePickerPlugin extends ImagePickerPlatform {
     return pickFile(accept: _kAcceptImageMimeType, capture: capture);
   }
 
+  /// Returns a [PickedFile] containing the video that was picked.
+  ///
+  /// The [source] argument controls where the video comes from. This can
+  /// be either [ImageSource.camera] or [ImageSource.gallery].
+  ///
+  /// Note that the `maxDuration` argument is not supported on the web. If the argument is supplied, it'll be silently ignored by the web version of the plugin.
+  ///
+  /// Use `preferredCameraDevice` to specify the camera to use when the `source` is [ImageSource.camera].
+  /// The `preferredCameraDevice` is ignored when `source` is [ImageSource.gallery]. It is also ignored if the chosen camera is not supported on the device.
+  /// Defaults to [CameraDevice.rear].
+  ///
+  /// If no images were picked, the return value is null.
   @override
   Future<PickedFile> pickVideo({
     required ImageSource source,
diff --git a/packages/image_picker/image_picker_for_web/pubspec.yaml b/packages/image_picker/image_picker_for_web/pubspec.yaml
@@ -2,7 +2,7 @@ name: image_picker_for_web
 description: Web platform implementation of image_picker
 homepage: https://github.com/flutter/plugins/tree/master/packages/image_picker/image_picker_for_web
 
-version: 2.0.0-nullsafety
+version: 2.0.0-nullsafety.1
 
 flutter:
   plugin:
