Update documentation in permission_status.dart (#1161)

* Update documentation in permission_status.dart

Updated the documentation to be clearer when limited and provisional statuses may be returned. The docs are repeated ~3 times, so I made them consistent.

* Updated the permanentlyDenied description per changes made in version 11.0.0

* Bumped the version in pubspec and CHANGELOG.

---------

Co-authored-by: Maurits van Beusekom <maurits@vnbskm.nl>

Author: bramp

permission_handler_platform_interface/CHANGELOG.md

@@ -1,3 +1,7 @@
+## 4.0.2
+
+* Improved the documentation around the `PermissionStatus`, `PermissionStatusGetters` and `FuturePermissionStatusGetters`.
+
 ## 4.0.1
 
 * Updates Android documentation on how to use `permission.photo` on Android 12 (API 32) and below and Android 13 (API 33) and above.

permission_handler_platform_interface/lib/src/permission_status.dart

@@ -2,8 +2,8 @@ part of permission_handler_platform_interface;
 
 /// Defines the state of a [Permission].
 enum PermissionStatus {
-  /// The user denied access to the requested feature,
-  /// permission needs to be asked first.
+  /// The user denied access to the requested feature, permission needs to be
+  /// asked first.
   denied,
 
   /// The user granted access to the requested feature.
@@ -12,19 +12,31 @@ enum PermissionStatus {
   /// The OS denied access to the requested feature. The user cannot change
   /// this app's status, possibly due to active restrictions such as parental
   /// controls being in place.
+  ///
   /// *Only supported on iOS.*
   restricted,
 
-  ///User has authorized this application for limited access.
+  /// The user has authorized this application for limited access. So far this
+  /// is only relevant for the Photo Library picker.
+  ///
   /// *Only supported on iOS (iOS14+).*
   limited,
 
   /// Permission to the requested feature is permanently denied, the permission
   /// dialog will not be shown when requesting this permission. The user may
   /// still change the permission status in the settings.
+  ///
+  /// *On Android:*
+  /// Android 11+ (API 30+): whether the user denied the permission for a second
+  /// time.
+  /// Below Android 11 (API 30): whether the user denied access to the requested
+  /// feature and selected to never again show a request.
+  ///
+  /// *On iOS:*
+  /// If the user has denied access to the requested feature.
   permanentlyDenied,
 
-  /// The application is provisionally authorized to post noninterruptive user
+  /// The application is provisionally authorized to post non-interruptive user
   /// notifications.
   ///
   /// *Only supported on iOS (iOS12+).*
@@ -68,8 +80,7 @@ extension PermissionStatusValue on PermissionStatus {
 
 /// Utility getter extensions for the [PermissionStatus] type.
 extension PermissionStatusGetters on PermissionStatus {
-  /// If the user denied access to the requested feature,
-  /// permission needs to be asked first.
+  /// If the user denied access to the requested feature.
   bool get isDenied => this == PermissionStatus.denied;
 
   /// If the user granted access to the requested feature.
@@ -78,9 +89,14 @@ extension PermissionStatusGetters on PermissionStatus {
   /// If the OS denied access to the requested feature. The user cannot change
   /// this app's status, possibly due to active restrictions such as parental
   /// controls being in place.
+  ///
   /// *Only supported on iOS.*
   bool get isRestricted => this == PermissionStatus.restricted;
 
+  /// If the permission to the requested feature is permanently denied, the
+  /// permission dialog will not be shown when requesting this permission. The
+  /// user may still change the permission status in the settings.
+  ///
   /// *On Android:*
   /// Android 11+ (API 30+): whether the user denied the permission for a second
   /// time.
@@ -90,17 +106,18 @@ extension PermissionStatusGetters on PermissionStatus {
   ///
   /// *On iOS:*
   /// If the user has denied access to the requested feature.
-  /// The user may still change the permission status in the settings
-  ///
-  /// WARNING: This can only be determined AFTER requesting this permission.
-  /// Therefore make a `request` call first.
   bool get isPermanentlyDenied => this == PermissionStatus.permanentlyDenied;
 
-  /// Indicates that permission for limited use of the resource is granted.
+  /// If the user has authorized this application for limited access. So far
+  /// this is only relevant for the Photo Library picker.
+  ///
+  /// *Only supported on iOS (iOS14+).*
   bool get isLimited => this == PermissionStatus.limited;
 
-  /// If the application is provisionally authorized to post noninterruptive
+  /// If the application is provisionally authorized to post non-interruptive
   /// user notifications.
+  ///
+  /// *Only supported on iOS (iOS12+).*
   bool get isProvisional => this == PermissionStatus.provisional;
 }
 
@@ -119,25 +136,30 @@ extension FuturePermissionStatusGetters on Future<PermissionStatus> {
   /// *Only supported on iOS.*
   Future<bool> get isRestricted async => (await this).isRestricted;
 
+  /// If the permission to the requested feature is permanently denied, the
+  /// permission dialog will not be shown when requesting this permission. The
+  /// user may still change the permission status in the settings.
+  ///
   /// *On Android:*
   /// Android 11+ (API 30+): whether the user denied the permission for a second
   /// time.
   /// Below Android 11 (API 30): whether the user denied access to the requested
   /// feature and selected to never again show a request.
-  /// The user may still change the permission status in the settings.
   ///
   /// *On iOS:*
   /// If the user has denied access to the requested feature.
-  /// The user may still change the permission status in the settings
   Future<bool> get isPermanentlyDenied async =>
       (await this).isPermanentlyDenied;
 
-  /// Indicates that permission for limited use of the resource is granted.
+  /// If the user has authorized this application for limited access. So far
+  /// this is only relevant for the Photo Library picker.
+  ///
+  /// *Only supported on iOS (iOS14+).*
   Future<bool> get isLimited async => (await this).isLimited;
 
-  /// If the application is provisionally authorized to post noninterruptive
+  /// If the application is provisionally authorized to post non-interruptive
   /// user notifications.
   ///
-  /// *Only supported on iOS.*
+  /// *Only supported on iOS (iOS12+).*
   Future<bool> get isProvisional async => (await this).isProvisional;
 }

permission_handler_platform_interface/pubspec.yaml

@@ -3,7 +3,7 @@ description: A common platform interface for the permission_handler plugin.
 homepage: https://github.com/baseflow/flutter-permission-handler/tree/master/permission_handler_platform_interface
 # NOTE: We strongly prefer non-breaking changes, even at the expense of a
 # less-clean API. See https://flutter.dev/go/platform-interface-breaking-changes
-version: 4.0.1
+version: 4.0.2
 
 dependencies:
   flutter: