Storage docs fixes (#12344)

Author: paulb777

FirebaseStorage/Sources/AsyncAwait.swift

@@ -24,8 +24,7 @@ public extension StorageReference {
   /// - Parameters:
   ///   - size: The maximum size in bytes to download. If the download exceeds this size,
   ///           the task will be cancelled and an error will be thrown.
-  /// - Throws:
-  ///   - An error if the operation failed, for example if the data exceeded `maxSize`.
+  /// - Throws: An error if the operation failed, for example if the data exceeded `maxSize`.
   /// - Returns: Data object.
   func data(maxSize: Int64) async throws -> Data {
     return try await withCheckedThrowingContinuation { continuation in
@@ -45,8 +44,7 @@ public extension StorageReference {
   ///              about the object being uploaded.
   ///   - onProgress: An optional closure function to return a `Progress` instance while the
   /// upload proceeds.
-  /// - Throws:
-  ///   - An error if the operation failed, for example if Storage was unreachable.
+  /// - Throws: An error if the operation failed, for example if Storage was unreachable.
   /// - Returns: StorageMetadata with additional information about the object being uploaded.
   func putDataAsync(_ uploadData: Data,
                     metadata: StorageMetadata? = nil,
@@ -83,9 +81,8 @@ public extension StorageReference {
   ///              about the object being uploaded.
   ///   - onProgress: An optional closure function to return a `Progress` instance while the
   /// upload proceeds.
-  /// - Throws:
-  ///   - An error if the operation failed, for example if no file was present at the specified
-  /// `url`.
+  /// - Throws: An error if the operation failed, for example if no file was present at the
+  /// specified `url`.
   /// - Returns: `StorageMetadata` with additional information about the object being uploaded.
   func putFileAsync(from url: URL,
                     metadata: StorageMetadata? = nil,
@@ -119,8 +116,7 @@ public extension StorageReference {
   ///   - fileUrl: A URL representing the system file path of the object to be uploaded.
   ///   - onProgress: An optional closure function to return a `Progress` instance while the
   /// download proceeds.
-  /// - Throws:
-  ///   - An error if the operation failed, for example if Storage was unreachable
+  /// - Throws: An error if the operation failed, for example if Storage was unreachable
   ///   or `fileURL` did not reference a valid path on disk.
   /// - Returns: A `URL` pointing to the file path of the downloaded file.
   func writeAsync(toFile fileURL: URL,
@@ -157,13 +153,11 @@ public extension StorageReference {
   /// Only available for projects using Firebase Rules Version 2.
   ///
   /// - Parameters:
-  ///   - maxResults The maximum number of results to return in a single page. Must be
+  ///   - maxResults: The maximum number of results to return in a single page. Must be
   ///                greater than 0 and at most 1000.
-  /// - Throws:
-  ///   - An error if the operation failed, for example if Storage was unreachable
+  /// - Throws: An error if the operation failed, for example if Storage was unreachable
   ///   or the storage reference referenced an invalid path.
-  /// - Returns:
-  ///   - A `StorageListResult` containing the contents of the storage reference.
+  /// - Returns: A `StorageListResult` containing the contents of the storage reference.
   func list(maxResults: Int64) async throws -> StorageListResult {
     typealias ListContinuation = CheckedContinuation<StorageListResult, Error>
     return try await withCheckedThrowingContinuation { (continuation: ListContinuation) in
@@ -182,9 +176,9 @@ public extension StorageReference {
   /// Only available for projects using Firebase Rules Version 2.
   ///
   /// - Parameters:
-  ///   - maxResults The maximum number of results to return in a single page. Must be
+  ///   - maxResults: The maximum number of results to return in a single page. Must be
   ///                greater than 0 and at most 1000.
-  ///   - pageToken A page token from a previous call to list.
+  ///   - pageToken: A page token from a previous call to list.
   /// - Throws:
   ///   - An error if the operation failed, for example if Storage was unreachable
   ///   or the storage reference referenced an invalid path.

FirebaseStorage/Sources/Result.swift

@@ -38,6 +38,7 @@ private func getResultCallback<T>(completion: @escaping (Result<T, Error>) -> Vo
 
 public extension StorageReference {
   /// Asynchronously retrieves a long lived download URL with a revokable token.
+  ///
   /// This can be used to share the file with others, but can be revoked by a developer
   /// in the Firebase Console.
   ///
@@ -48,6 +49,7 @@ public extension StorageReference {
   }
 
   /// Asynchronously downloads the object at the `StorageReference` to a `Data` object.
+  ///
   /// A `Data` of the provided max size will be allocated, so ensure that the device has enough
   /// memory to complete. For downloading large files, the `write` API may be a better option.
 
@@ -73,6 +75,7 @@ public extension StorageReference {
   }
 
   /// Resumes a previous `list` call, starting after a pagination token.
+  ///
   /// Returns the next set of items (files) and prefixes (folders) under this StorageReference.
   ///
   /// "/" is treated as a path delimiter. Firebase Storage does not support unsupported object
@@ -82,10 +85,10 @@ public extension StorageReference {
   /// Only available for projects using Firebase Rules Version 2.
   ///
   /// - Parameters:
-  ///   - maxResults The maximum number of results to return in a single page. Must be
+  ///   - maxResults: The maximum number of results to return in a single page. Must be
   ///                greater than 0 and at most 1000.
-  ///   - pageToken A page token from a previous call to list.
-  ///   - completion A completion handler that will be invoked with the next items and
+  ///   - pageToken: A page token from a previous call to list.
+  ///   - completion: A completion handler that will be invoked with the next items and
   ///                prefixes under the current StorageReference. It returns a `Result` enum
   ///                with either the list or an `Error`.
   func list(maxResults: Int64,
@@ -105,9 +108,9 @@ public extension StorageReference {
   /// Only available for projects using Firebase Rules Version 2.
   ///
   /// - Parameters:
-  ///   - maxResults The maximum number of results to return in a single page. Must be
+  ///   - maxResults: The maximum number of results to return in a single page. Must be
   ///                greater than 0 and at most 1000.
-  ///   - completion A completion handler that will be invoked with the next items and
+  ///   - completion: A completion handler that will be invoked with the next items and
   ///                prefixes under the current `StorageReference`. It returns a `Result` enum
   ///                with either the list or an `Error`.
   func list(maxResults: Int64,
@@ -125,7 +128,7 @@ public extension StorageReference {
   /// Only available for projects using Firebase Rules Version 2.
   ///
   /// - Parameters:
-  ///   - completion A completion handler that will be invoked with all items and prefixes
+  ///   - completion: A completion handler that will be invoked with all items and prefixes
   ///                under the current StorageReference. It returns a `Result` enum with either the
   ///                list or an `Error`.
   func listAll(completion: @escaping (Result<StorageListResult, Error>) -> Void) {
@@ -136,10 +139,10 @@ public extension StorageReference {
   /// This is not recommended for large files, and one should instead upload a file from disk.
   ///
   /// - Parameters:
-  ///   - uploadData The `Data` to upload.
-  ///   - metadata `StorageMetadata` containing additional information (MIME type, etc.)
+  ///   - uploadData: The `Data` to upload.
+  ///   - metadata: `StorageMetadata` containing additional information (MIME type, etc.)
   ///              about the object being uploaded.
-  ///   - completion A completion block that returns a `Result` enum with either the
+  ///   - completion: A completion block that returns a `Result` enum with either the
   ///                object metadata or an `Error`.
   ///
   /// - Returns: An instance of `StorageUploadTask`, which can be used to monitor or manage
@@ -157,10 +160,10 @@ public extension StorageReference {
   /// Asynchronously uploads a file to the currently specified `StorageReference`.
   ///
   /// - Parameters:
-  ///   - from A URL representing the system file path of the object to be uploaded.
-  ///   - metadata `StorageMetadata` containing additional information (MIME type, etc.)
+  ///   - from: A URL representing the system file path of the object to be uploaded.
+  ///   - metadata: `StorageMetadata` containing additional information (MIME type, etc.)
   ///              about the object being uploaded.
-  ///   - completion A completion block that returns a `Result` enum with either the
+  ///   - completion: A completion block that returns a `Result` enum with either the
   ///                object metadata or an `Error`.
   ///
   /// - Returns: An instance of `StorageUploadTask`, which can be used to monitor or manage
@@ -178,8 +181,8 @@ public extension StorageReference {
   /// Updates the metadata associated with an object at the current path.
   ///
   /// - Parameters:
-  ///   - metadata A `StorageMetadata` object with the metadata to update.
-  ///   - completion A completion block which returns a `Result` enum with either the
+  ///   - metadata: A `StorageMetadata` object with the metadata to update.
+  ///   - completion: A completion block which returns a `Result` enum with either the
   ///                object metadata or an `Error`.
   func updateMetadata(_ metadata: StorageMetadata,
                       completion: @escaping (Result<StorageMetadata, Error>) -> Void) {
@@ -189,8 +192,8 @@ public extension StorageReference {
   /// Asynchronously downloads the object at the current path to a specified system filepath.
   ///
   /// - Parameters:
-  ///   - toFile A file system URL representing the path the object should be downloaded to.
-  ///   - completion A completion block that fires when the file download completes. The
+  ///   - toFile: A file system URL representing the path the object should be downloaded to.
+  ///   - completion: A completion block that fires when the file download completes. The
   ///                block returns a `Result` enum with either an NSURL pointing to the file
   ///                path of the downloaded file or an `Error`.
   ///