(#7) Add missing docs to the new SAF APIs

Author: LaksCastro

lib/src/storage_access_framework/storage_access_framework.dart

@@ -2,8 +2,15 @@ import 'package:shared_storage/shared_storage.dart';
 import 'package:shared_storage/src/method_channel.dart';
 import 'package:shared_storage/src/storage_access_framework/uri_permission.dart';
 
-/// TODO: Add [initialDir] param as mentioned here:
-/// TODO: Add documentation
+/// Start Activity Action: Allow the user to pick a directory subtree.
+/// When invoked, the system will display the various `DocumentsProvider`
+/// instances installed on the device, letting the user navigate through them.
+/// Apps can fully manage documents within the returned directory.
+///
+/// [Refer to details](https://developer.android.com/reference/android/content/Intent#ACTION_OPEN_DOCUMENT_TREE)
+///
+/// TODO: Implement [initialDir] param to
+/// support the initial directory of the directory picker
 Future<Uri?> openDocumentTree() async {
   const kOpenDocumentTree = 'openDocumentTree';
 
@@ -15,7 +22,18 @@ Future<Uri?> openDocumentTree() async {
   return Uri.parse(selectedDirectoryUri);
 }
 
-/// TODO: Add documentation
+/// Starts Activity Action: Allow the user to create a new document.
+/// When invoked, the system will display the various `DocumentsProvider`
+/// instances installed on the device, letting the user navigate through them.
+/// The returned document may be a newly created document with no content,
+/// or it may be an existing document with the requested MIME type.
+///
+/// - [mimeType] is the kind of file that you want to create
+/// - [content] the file content, will be converted to bytes `List<Int>`
+/// - [displayName] the name of the file without any extension
+/// - [directory] Needs to be the [URI] directory returned by `openDocumentTree`
+///
+/// [Refer to details](https://developer.android.com/reference/android/content/Intent#ACTION_CREATE_DOCUMENT)
 Future<Uri?> createDocumentFile({
   required String mimeType,
   required String content,
@@ -46,6 +64,10 @@ Future<Uri?> createDocumentFile({
   return Uri.parse(createdFileUri);
 }
 
+/// Returns an `List<URI>` with all persisted [URI]
+///
+/// To persist an [URI] call `openDocumentTree`
+/// and to remove an persisted [URI] call `releasePersistableUriPermission`
 Future<List<UriPermission>?> persistedUriPermissions() async {
   const kPersistedUriPermissions = 'persistedUriPermissions';
 
@@ -60,6 +82,12 @@ Future<List<UriPermission>?> persistedUriPermissions() async {
       .toList();
 }
 
+/// Will revoke an persistable URI
+///
+/// Call this when your App no longer wants the permission of an [URI] returned
+/// by `openDocumentTree` method
+///
+/// To get the current persisted [URI]s call `persistedUriPermissions`
 Future<void> releasePersistableUriPermission(Uri directory) async {
   const kReleasePersistableUriPermission = 'releasePersistableUriPermission';
 
@@ -73,7 +101,8 @@ Future<void> releasePersistableUriPermission(Uri directory) async {
 /// Convenient method to verify if a given [uri]
 /// is allowed to be write or read from SAF API's
 ///
-/// TODO: Improve documentation
+/// This uses the `releasePersistableUriPermission` method to get the List
+/// of allowed [URI]s then will verify if the [uri] is included in
 Future<bool> isPersistedUri(Uri uri) async {
   final persistedUris = await persistedUriPermissions();
 

lib/src/storage_access_framework/uri_permission.dart

@@ -4,11 +4,26 @@
 ///
 /// [Refer to details](https://developer.android.com/reference/android/content/UriPermission)
 class UriPermission {
+  /// Whether an [UriPermission] is created with [`FLAG_GRANT_READ_URI_PERMISSION`](https://developer.android.com/reference/android/content/Intent#FLAG_GRANT_READ_URI_PERMISSION)
   final bool isReadPermission;
+
+  /// Whether an [UriPermission] is created with [`FLAG_GRANT_WRITE_URI_PERMISSION`](https://developer.android.com/reference/android/content/Intent#FLAG_GRANT_WRITE_URI_PERMISSION)
   final bool isWritePermission;
+
+  /// Return the time when this permission was first persisted, in milliseconds
+  /// since January 1, 1970 00:00:00.0 UTC. Returns `INVALID_TIME` if
+  /// not persisted.
+  ///
+  /// [Refer to details](https://android.googlesource.com/platform/frameworks/base/+/master/core/java/android/content/UriPermission.java#77)
   final int persistedTime;
+
+  /// Return the Uri this permission pertains to.
+  ///
+  /// [Refer to details](https://android.googlesource.com/platform/frameworks/base/+/master/core/java/android/content/UriPermission.java#56)
   final Uri uri;
 
+  /// Even we allow create instances of this class avoid it and use
+  /// `persistedUriPermissions` API instead
   const UriPermission(
       {required this.isReadPermission,
       required this.isWritePermission,