From 2d3ecf96588079a19734d32713f44e22b1b41451 Mon Sep 17 00:00:00 2001 From: Paul Beusterien Date: Thu, 1 Feb 2024 14:57:41 -0800 Subject: [PATCH] Storage docs fixes (#12344) --- FirebaseStorage/Sources/AsyncAwait.swift | 26 +- FirebaseStorage/Sources/Result.swift | 35 +- FirebaseStorage/Sources/Storage.swift | 188 ++++---- .../Sources/StorageDownloadTask.swift | 3 + .../Sources/StorageListResult.swift | 8 +- FirebaseStorage/Sources/StorageMetadata.swift | 13 +- .../Sources/StorageObservableTask.swift | 5 +- .../Sources/StorageReference.swift | 418 ++++++++---------- FirebaseStorage/Sources/StorageTask.swift | 2 + .../Sources/StorageUploadTask.swift | 3 + 10 files changed, 318 insertions(+), 383 deletions(-) diff --git a/FirebaseStorage/Sources/AsyncAwait.swift b/FirebaseStorage/Sources/AsyncAwait.swift index d38c859d818..564a2378aaa 100644 --- a/FirebaseStorage/Sources/AsyncAwait.swift +++ b/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 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. diff --git a/FirebaseStorage/Sources/Result.swift b/FirebaseStorage/Sources/Result.swift index 7aee82f439c..d1260fe57f9 100644 --- a/FirebaseStorage/Sources/Result.swift +++ b/FirebaseStorage/Sources/Result.swift @@ -38,6 +38,7 @@ private func getResultCallback(completion: @escaping (Result) -> 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) -> 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) -> 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`. /// diff --git a/FirebaseStorage/Sources/Storage.swift b/FirebaseStorage/Sources/Storage.swift index 197122d05bd..c4590bd28e7 100644 --- a/FirebaseStorage/Sources/Storage.swift +++ b/FirebaseStorage/Sources/Storage.swift @@ -26,61 +26,53 @@ import FirebaseCore // Avoids exposing internal FirebaseCore APIs to Swift users. @_implementationOnly import FirebaseCoreExtension -/** - * Firebase Storage is a service that supports uploading and downloading binary objects, - * such as images, videos, and other files to Google Cloud Storage. Instances of `Storage` - * are not thread-safe, but can be accessed from any thread. - * - * If you call `Storage.storage()`, the instance will initialize with the default `FirebaseApp`, - * `FirebaseApp.app()`, and the storage location will come from the provided - * `GoogleService-Info.plist`. - * - * If you provide a custom instance of `FirebaseApp`, - * the storage location will be specified via the `FirebaseOptions.storageBucket` property. - */ +/// Firebase Storage is a service that supports uploading and downloading binary objects, +/// such as images, videos, and other files to Google Cloud Storage. Instances of `Storage` +/// are not thread-safe, but can be accessed from any thread. +/// +/// If you call `Storage.storage()`, the instance will initialize with the default `FirebaseApp`, +/// `FirebaseApp.app()`, and the storage location will come from the provided +/// `GoogleService-Info.plist`. +/// +/// If you provide a custom instance of `FirebaseApp`, +/// the storage location will be specified via the `FirebaseOptions.storageBucket` property. @objc(FIRStorage) open class Storage: NSObject { // MARK: - Public APIs - /** - * The default `Storage` instance. - * - Returns: An instance of `Storage`, configured with the default `FirebaseApp`. - */ + /// The default `Storage` instance. + /// - Returns: An instance of `Storage`, configured with the default `FirebaseApp`. @objc(storage) open class func storage() -> Storage { return storage(app: FirebaseApp.app()!) } - /** - * A method used to create `Storage` instances initialized with a custom storage bucket URL. - * Any `StorageReferences` generated from this instance of `Storage` will reference files - * and directories within the specified bucket. - * - Parameter url The `gs://` URL to your Firebase Storage bucket. - * - Returns: A `Storage` instance, configured with the custom storage bucket. - */ + /// A method used to create `Storage` instances initialized with a custom storage bucket URL. + /// + /// Any `StorageReferences` generated from this instance of `Storage` will reference files + /// and directories within the specified bucket. + /// - Parameter url: The `gs://` URL to your Firebase Storage bucket. + /// - Returns: A `Storage` instance, configured with the custom storage bucket. @objc(storageWithURL:) open class func storage(url: String) -> Storage { return storage(app: FirebaseApp.app()!, url: url) } - /** - * Creates an instance of `Storage`, configured with a custom `FirebaseApp`. `StorageReference`s - * generated from a resulting instance will reference files in the Firebase project - * associated with custom `FirebaseApp`. - * - Parameter app The custom `FirebaseApp` used for initialization. - * - Returns: A `Storage` instance, configured with the custom `FirebaseApp`. - */ + /// Creates an instance of `Storage`, configured with a custom `FirebaseApp`. `StorageReference`s + /// generated from a resulting instance will reference files in the Firebase project + /// associated with custom `FirebaseApp`. + /// - Parameter app: The custom `FirebaseApp` used for initialization. + /// - Returns: A `Storage` instance, configured with the custom `FirebaseApp`. @objc(storageForApp:) open class func storage(app: FirebaseApp) -> Storage { let provider = ComponentType.instance(for: StorageProvider.self, in: app.container) return provider.storage(for: Storage.bucket(for: app)) } - /** - * Creates an instance of `Storage`, configured with a custom `FirebaseApp` and a custom storage - * bucket URL. - * - Parameters: - * - app: The custom `FirebaseApp` used for initialization. - * - url: The `gs://` url to your Firebase Storage bucket. - * - Returns: the `Storage` instance, configured with the custom `FirebaseApp` and storage bucket URL. - */ + /// Creates an instance of `Storage`, configured with a custom `FirebaseApp` and a custom storage + /// bucket URL. + /// - Parameters: + /// - app: The custom `FirebaseApp` used for initialization. + /// - url: The `gs://` url to your Firebase Storage bucket. + /// - Returns: The `Storage` instance, configured with the custom `FirebaseApp` and storage bucket + /// URL. @objc(storageForApp:URL:) open class func storage(app: FirebaseApp, url: String) -> Storage { let provider = ComponentType.instance(for: StorageProvider.self, @@ -88,50 +80,40 @@ import FirebaseCore return provider.storage(for: Storage.bucket(for: app, urlString: url)) } - /** - * The `FirebaseApp` associated with this Storage instance. - */ + /// The `FirebaseApp` associated with this Storage instance. @objc public let app: FirebaseApp - /** - * The maximum time in seconds to retry an upload if a failure occurs. - * Defaults to 10 minutes (600 seconds). - */ + /// The maximum time in seconds to retry an upload if a failure occurs. + /// Defaults to 10 minutes (600 seconds). @objc public var maxUploadRetryTime: TimeInterval { didSet { maxUploadRetryInterval = Storage.computeRetryInterval(fromRetryTime: maxUploadRetryTime) } } - /** - * The maximum time in seconds to retry a download if a failure occurs. - * Defaults to 10 minutes (600 seconds). - */ + /// The maximum time in seconds to retry a download if a failure occurs. + /// Defaults to 10 minutes (600 seconds). @objc public var maxDownloadRetryTime: TimeInterval { didSet { maxDownloadRetryInterval = Storage.computeRetryInterval(fromRetryTime: maxDownloadRetryTime) } } - /** - * The maximum time in seconds to retry operations other than upload and download if a failure occurs. - * Defaults to 2 minutes (120 seconds). - */ + /// The maximum time in seconds to retry operations other than upload and download if a failure + /// occurs. + /// Defaults to 2 minutes (120 seconds). @objc public var maxOperationRetryTime: TimeInterval { didSet { maxOperationRetryInterval = Storage.computeRetryInterval(fromRetryTime: maxOperationRetryTime) } } - /** - * Specify the maximum upload chunk size. Values less than 256K (262144) will be rounded up to 256K. Values - * above 256K will be rounded down to the nearest 256K multiple. The default is no maximum. - */ + /// Specify the maximum upload chunk size. Values less than 256K (262144) will be rounded up to + /// 256K. Values + /// above 256K will be rounded down to the nearest 256K multiple. The default is no maximum. @objc public var uploadChunkSizeBytes: Int64 = .max - /** - * A `DispatchQueue` that all developer callbacks are fired on. Defaults to the main queue. - */ + /// A `DispatchQueue` that all developer callbacks are fired on. Defaults to the main queue. @objc public var callbackQueue: DispatchQueue { get { ensureConfigured() @@ -146,26 +128,25 @@ import FirebaseCore } } - /** - * Creates a `StorageReference` initialized at the root Firebase Storage location. - * - Returns: An instance of `StorageReference` referencing the root of the storage bucket. - */ + /// Creates a `StorageReference` initialized at the root Firebase Storage location. + /// - Returns: An instance of `StorageReference` referencing the root of the storage bucket. @objc open func reference() -> StorageReference { ensureConfigured() let path = StoragePath(with: storageBucket) return StorageReference(storage: self, path: path) } - /** - * Creates a StorageReference given a `gs://`, `http://`, or `https://` URL pointing to a - * Firebase Storage location. For example, you can pass in an `https://` download URL retrieved from - * `StorageReference.downloadURL(completion:)` or the `gs://` URL from - * `StorageReference.description`. - * - Parameter url A gs:// or https:// URL to initialize the reference with. - * - Returns: An instance of StorageReference at the given child path. - * - Throws: Throws a fatal error if `url` is not associated with the `FirebaseApp` used to initialize - * this Storage instance. - */ + /// Creates a StorageReference given a `gs://`, `http://`, or `https://` URL pointing to a + /// Firebase Storage location. + /// + /// For example, you can pass in an `https://` download URL retrieved from + /// `StorageReference.downloadURL(completion:)` or the `gs://` URL from + /// `StorageReference.description`. + /// - Parameter url: A gs:// or https:// URL to initialize the reference with. + /// - Returns: An instance of StorageReference at the given child path. + /// - Throws: Throws a fatal error if `url` is not associated with the `FirebaseApp` used to + /// initialize + /// this Storage instance. @objc open func reference(forURL url: String) -> StorageReference { ensureConfigured() do { @@ -188,16 +169,16 @@ import FirebaseCore } } - /** - * Creates a StorageReference given a `gs://`, `http://`, or `https://` URL pointing to a - * Firebase Storage location. For example, you can pass in an `https://` download URL retrieved from - * `StorageReference.downloadURL(completion:)` or the `gs://` URL from - * `StorageReference.description`. - * - Parameter url A gs:// or https:// URL to initialize the reference with. - * - Returns: An instance of StorageReference at the given child path. - * - Throws: Throws an Error if `url` is not associated with the `FirebaseApp` used to initialize - * this Storage instance. - */ + /// Creates a StorageReference given a `gs://`, `http://`, or `https://` URL pointing to a + /// Firebase Storage location. + /// + /// For example, you can pass in an `https://` download URL retrieved from + /// `StorageReference.downloadURL(completion:)` or the `gs://` URL from + /// `StorageReference.description`. + /// - Parameter url: A gs:// or https:// URL to initialize the reference with. + /// - Returns: An instance of StorageReference at the given child path. + /// - Throws: Throws an Error if `url` is not associated with the `FirebaseApp` used to initialize + /// this Storage instance. open func reference(for url: URL) throws -> StorageReference { ensureConfigured() var path: StoragePath @@ -222,20 +203,20 @@ import FirebaseCore return StorageReference(storage: self, path: path) } - /** - * Creates a `StorageReference` initialized at a location specified by the `path` parameter. - * - Parameter path A relative path from the root of the storage bucket, - * for instance @"path/to/object". - * - Returns: An instance of `StorageReference` pointing to the given path. - */ + /// Creates a `StorageReference` initialized at a location specified by the `path` parameter. + /// - Parameter path: A relative path from the root of the storage bucket, + /// for instance @"path/to/object". + /// - Returns: An instance of `StorageReference` pointing to the given path. @objc(referenceWithPath:) open func reference(withPath path: String) -> StorageReference { return reference().child(path) } - /** - * Configures the Storage SDK to use an emulated backend instead of the default remote backend. - * This method should be called before invoking any other methods on a new instance of `Storage`. - */ + /// Configures the Storage SDK to use an emulated backend instead of the default remote backend. + /// + /// This method should be called before invoking any other methods on a new instance of `Storage`. + /// - Parameter host: A string specifying the host. + /// - Parameter port: The port specified as an `Int`. + @objc open func useEmulator(withHost host: String, port: Int) { guard host.count > 0 else { fatalError("Invalid host argument: Cannot connect to empty host.") @@ -364,14 +345,13 @@ import FirebaseCore var maxOperationRetryInterval: TimeInterval var maxUploadRetryInterval: TimeInterval - /** - * Performs a crude translation of the user provided timeouts to the retry intervals that - * GTMSessionFetcher accepts. GTMSessionFetcher times out operations if the time between individual - * retry attempts exceed a certain threshold, while our API contract looks at the total observed - * time of the operation (i.e. the sum of all retries). - * @param retryTime A timeout that caps the sum of all retry attempts - * @return A timeout that caps the timeout of the last retry attempt - */ + /// Performs a crude translation of the user provided timeouts to the retry intervals that + /// GTMSessionFetcher accepts. GTMSessionFetcher times out operations if the time between + /// individual + /// retry attempts exceed a certain threshold, while our API contract looks at the total observed + /// time of the operation (i.e. the sum of all retries). + /// @param retryTime A timeout that caps the sum of all retry attempts + /// @return A timeout that caps the timeout of the last retry attempt static func computeRetryInterval(fromRetryTime retryTime: TimeInterval) -> TimeInterval { // GTMSessionFetcher's retry starts at 1 second and then doubles every time. We use this // information to compute a best-effort estimate of what to translate the user provided retry @@ -387,9 +367,7 @@ import FirebaseCore return lastInterval } - /** - * Configures the storage instance. Freezes the host setting. - */ + /// Configures the storage instance. Freezes the host setting. private func ensureConfigured() { guard fetcherService == nil else { return diff --git a/FirebaseStorage/Sources/StorageDownloadTask.swift b/FirebaseStorage/Sources/StorageDownloadTask.swift index b37eedc7dfe..62217182c0e 100644 --- a/FirebaseStorage/Sources/StorageDownloadTask.swift +++ b/FirebaseStorage/Sources/StorageDownloadTask.swift @@ -22,10 +22,13 @@ import Foundation /** * `StorageDownloadTask` implements resumable downloads from an object in Firebase Storage. + * * Downloads can be returned on completion with a completion handler, and can be monitored * by attaching observers, or controlled by calling `pause()`, `resume()`, * or `cancel()`. + * * Downloads can currently be returned as `Data` in memory, or as a `URL` to a file on disk. + * * Downloads are performed on a background queue, and callbacks are raised on the developer * specified `callbackQueue` in Storage, or the main queue if left unspecified. */ diff --git a/FirebaseStorage/Sources/StorageListResult.swift b/FirebaseStorage/Sources/StorageListResult.swift index 872db7140f9..b32f62bf0d8 100644 --- a/FirebaseStorage/Sources/StorageListResult.swift +++ b/FirebaseStorage/Sources/StorageListResult.swift @@ -18,23 +18,17 @@ import Foundation @objc(FIRStorageListResult) open class StorageListResult: NSObject { /** * The prefixes (folders) returned by a `list()` operation. - * - * - Returns: A list of prefixes (folders). */ @objc public let prefixes: [StorageReference] /** * The objects (files) returned by a `list()` operation. - * - * - Returns: A page token if more results are available. */ @objc public let items: [StorageReference] /** - * Returns a token that can be used to resume a previous `list()` operation. `nil` + * A token that can be used to resume a previous `list()` operation. `nil` * indicates that there are no more results. - * - * - Returns: A page token if more results are available. */ @objc public let pageToken: String? diff --git a/FirebaseStorage/Sources/StorageMetadata.swift b/FirebaseStorage/Sources/StorageMetadata.swift index 770aeada8f1..0f45ca345a5 100644 --- a/FirebaseStorage/Sources/StorageMetadata.swift +++ b/FirebaseStorage/Sources/StorageMetadata.swift @@ -15,11 +15,12 @@ import Foundation /** - * Class which represents the metadata on an object in Firebase Storage. This metadata is + * Class which represents the metadata on an object in Firebase Storage. + * + * This metadata is * returned on successful operations, and can be used to retrieve download URLs, content types, - * and a Storage reference to the object in question. Full documentation can be found at the GCS - * Objects#resource docs. - * @see https://cloud.google.com/storage/docs/json_api/v1/objects#resource + * and a Storage reference to the object in question. Full documentation can be found in the + * [GCS documentation](https://cloud.google.com/storage/docs/json_api/v1/objects#resource) */ @objc(FIRStorageMetadata) open class StorageMetadata: NSObject { // MARK: - Public APIs @@ -145,6 +146,10 @@ import Foundation // MARK: - Public Initializers + /** + * Creates an empty instance of StorageMetadata. + * @return An empty instance of StorageMetadata. + */ @objc override public convenience init() { self.init(dictionary: [:]) } diff --git a/FirebaseStorage/Sources/StorageObservableTask.swift b/FirebaseStorage/Sources/StorageObservableTask.swift index 33a9667f420..f302fe152be 100644 --- a/FirebaseStorage/Sources/StorageObservableTask.swift +++ b/FirebaseStorage/Sources/StorageObservableTask.swift @@ -23,6 +23,7 @@ import Foundation /** * An extended `StorageTask` providing observable semantics that can be used for responding to changes * in task state. + * * Observers produce a `StorageHandle`, which is used to keep track of and remove specific * observers at a later date. */ @@ -80,7 +81,7 @@ import Foundation /** * Removes the single observer with the provided handle. - * - Parameter handle The handle of the task to remove. + * - Parameter handle: The handle of the task to remove. */ @objc(removeObserverWithHandle:) open func removeObserver(withHandle handle: String) { if let status = handleToStatusMap[handle] { @@ -93,7 +94,7 @@ import Foundation /** * Removes all observers for a single status. - * - Parameter status A `StorageTaskStatus` to remove all listeners for. + * - Parameter status: A `StorageTaskStatus` to remove all listeners for. */ @objc(removeAllObserversForStatus:) open func removeAllObservers(for status: StorageTaskStatus) { diff --git a/FirebaseStorage/Sources/StorageReference.swift b/FirebaseStorage/Sources/StorageReference.swift index d81377d5c7d..98eb595c733 100644 --- a/FirebaseStorage/Sources/StorageReference.swift +++ b/FirebaseStorage/Sources/StorageReference.swift @@ -14,61 +14,49 @@ import Foundation -/** - * `StorageReference` represents a reference to a Google Cloud Storage object. Developers can - * upload and download objects, as well as get/set object metadata, and delete an object at the - * path. See the Cloud docs for more details: https://cloud.google.com/storage/ - */ - +/// `StorageReference` represents a reference to a Google Cloud Storage object. Developers can +/// upload and download objects, as well as get/set object metadata, and delete an object at the +/// path. See the [Cloud docs](https://cloud.google.com/storage/) for more details. @objc(FIRStorageReference) open class StorageReference: NSObject { // MARK: - Public APIs - /** - * The `Storage` service object which created this reference. - */ + /// The `Storage` service object which created this reference. @objc public let storage: Storage - /** - * The name of the Google Cloud Storage bucket associated with this reference. - * For example, in `gs://bucket/path/to/object.txt`, the bucket would be 'bucket'. - */ + /// The name of the Google Cloud Storage bucket associated with this reference. + /// For example, in `gs://bucket/path/to/object.txt`, the bucket would be 'bucket'. @objc public var bucket: String { return path.bucket } - /** - * The full path to this object, not including the Google Cloud Storage bucket. - * In `gs://bucket/path/to/object.txt`, the full path would be: `path/to/object.txt` - */ + /// The full path to this object, not including the Google Cloud Storage bucket. + /// In `gs://bucket/path/to/object.txt`, the full path would be: `path/to/object.txt`. @objc public var fullPath: String { return path.object ?? "" } - /** - * The short name of the object associated with this reference. - * In `gs://bucket/path/to/object.txt`, the name of the object would be `object.txt`. - */ + /// The short name of the object associated with this reference. + /// + /// In `gs://bucket/path/to/object.txt`, the name of the object would be `object.txt`. @objc public var name: String { return (path.object as? NSString)?.lastPathComponent ?? "" } - /** - * Creates a new `StorageReference` pointing to the root object. - * - Returns: A new `StorageReference` pointing to the root object. - */ + /// Creates a new `StorageReference` pointing to the root object. + /// - Returns: A new `StorageReference` pointing to the root object. @objc open func root() -> StorageReference { return StorageReference(storage: storage, path: path.root()) } - /** - * Creates a new `StorageReference` pointing to the parent of the current reference - * or `nil` if this instance references the root location. - * For example: - * path = foo/bar/baz parent = foo/bar - * path = foo parent = (root) - * path = (root) parent = nil - * - Returns: A new `StorageReference` pointing to the parent of the current reference. - */ + /// Creates a new `StorageReference` pointing to the parent of the current reference + /// or `nil` if this instance references the root location. + /// ``` + /// For example: + /// path = foo/bar/baz parent = foo/bar + /// path = foo parent = (root) + /// path = (root) parent = nil + /// ``` + /// - Returns: A new `StorageReference` pointing to the parent of the current reference. @objc open func parent() -> StorageReference? { guard let parentPath = path.parent() else { return nil @@ -76,61 +64,59 @@ import Foundation return StorageReference(storage: storage, path: parentPath) } - /** - * Creates a new `StorageReference` pointing to a child object of the current reference. - * path = foo child = bar newPath = foo/bar - * path = foo/bar child = baz ntask.impl.snapshotwPath = foo/bar/baz - * All leading and trailing slashes will be removed, and consecutive slashes will be - * compressed to single slashes. For example: - * child = /foo/bar newPath = foo/bar - * child = foo/bar/ newPath = foo/bar - * child = foo///bar newPath = foo/bar - * - Parameter path The path to append to the current path. - * - Returns: A new `StorageReference` pointing to a child location of the current reference. - */ + /// Creates a new `StorageReference` pointing to a child object of the current reference. + /// ``` + /// path = foo child = bar newPath = foo/bar + /// path = foo/bar child = baz ntask.impl.snapshotwPath = foo/bar/baz + /// All leading and trailing slashes will be removed, and consecutive slashes will be + /// compressed to single slashes. For example: + /// child = /foo/bar newPath = foo/bar + /// child = foo/bar/ newPath = foo/bar + /// child = foo///bar newPath = foo/bar + /// ``` + /// + /// - Parameter path: The path to append to the current path. + /// - Returns: A new `StorageReference` pointing to a child location of the current reference. @objc(child:) open func child(_ path: String) -> StorageReference { return StorageReference(storage: storage, path: self.path.child(path)) } // MARK: - Uploads - /** - * Asynchronously uploads data to the currently specified `StorageReference`, - * without additional metadata. - * 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.) - * about the object being uploaded. - * - Returns: An instance of `StorageUploadTask`, which can be used to monitor or manage the upload. - */ + /// Asynchronously uploads data to the currently specified `StorageReference`, + /// without additional metadata. + /// 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.) + /// about the object being uploaded. + /// - Returns: An instance of `StorageUploadTask`, which can be used to monitor or manage the + /// upload. @objc(putData:metadata:) @discardableResult open func putData(_ uploadData: Data, metadata: StorageMetadata? = nil) -> StorageUploadTask { return putData(uploadData, metadata: metadata, completion: nil) } - /** - * Asynchronously uploads data to the currently specified `StorageReference`. - * This is not recommended for large files, and one should instead upload a file from disk. - * - Parameter uploadData The data to upload. - * - Returns: An instance of `StorageUploadTask`, which can be used to monitor or manage the upload. - */ + /// Asynchronously uploads data to the currently specified `StorageReference`. + /// This is not recommended for large files, and one should instead upload a file from disk. + /// - Parameter uploadData The data to upload. + /// - Returns: An instance of `StorageUploadTask`, which can be used to monitor or manage the + /// upload. @objc(putData:) @discardableResult open func __putData(_ uploadData: Data) -> StorageUploadTask { return putData(uploadData, metadata: nil, completion: nil) } - /** - * Asynchronously uploads data to the currently specified `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.) - * about the object being uploaded. - * - completion: A closure that either returns the object metadata on success, - * or an error on failure. - * - Returns: An instance of `StorageUploadTask`, which can be used to monitor or manage the upload. - */ + /// Asynchronously uploads data to the currently specified `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.) + /// about the object being uploaded. + /// - completion: A closure that either returns the object metadata on success, + /// or an error on failure. + /// - Returns: An instance of `StorageUploadTask`, which can be used to monitor or manage the + /// upload. @objc(putData:metadata:completion:) @discardableResult open func putData(_ uploadData: Data, metadata: StorageMetadata? = nil, @@ -149,42 +135,38 @@ import Foundation return task } - /** - * Asynchronously uploads a file to the currently specified `StorageReference`. - * `putData` should be used instead of `putFile` in Extensions. - * - Parameters: - * - fileURL: 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. - * - Returns: An instance of `StorageUploadTask`, which can be used to monitor or manage the upload. - */ + /// Asynchronously uploads a file to the currently specified `StorageReference`. + /// `putData` should be used instead of `putFile` in Extensions. + /// - Parameters: + /// - fileURL: 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. + /// - Returns: An instance of `StorageUploadTask`, which can be used to monitor or manage the + /// upload. @objc(putFile:metadata:) @discardableResult open func putFile(from fileURL: URL, metadata: StorageMetadata? = nil) -> StorageUploadTask { return putFile(from: fileURL, metadata: metadata, completion: nil) } - /** - * Asynchronously uploads a file to the currently specified `StorageReference`, - * without additional metadata. - * `putData` should be used instead of `putFile` in Extensions. - * @param fileURL A URL representing the system file path of the object to be uploaded. - * @return An instance of StorageUploadTask, which can be used to monitor or manage the upload. - */ + /// Asynchronously uploads a file to the currently specified `StorageReference`, + /// without additional metadata. + /// `putData` should be used instead of `putFile` in Extensions. + /// @param fileURL A URL representing the system file path of the object to be uploaded. + /// @return An instance of StorageUploadTask, which can be used to monitor or manage the upload. @objc(putFile:) @discardableResult open func __putFile(from fileURL: URL) -> StorageUploadTask { return putFile(from: fileURL, metadata: nil, completion: nil) } - /** - * Asynchronously uploads a file to the currently specified `StorageReference`. - * `putData` should be used instead of `putFile` in Extensions. - * - Parameters: - * - fileURL: 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 either returns the object metadata on success, - * or an error on failure. - * - Returns: An instance of `StorageUploadTask`, which can be used to monitor or manage the upload. - */ + /// Asynchronously uploads a file to the currently specified `StorageReference`. + /// `putData` should be used instead of `putFile` in Extensions. + /// - Parameters: + /// - fileURL: 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 either returns the object metadata on success, + /// or an error on failure. + /// - Returns: An instance of `StorageUploadTask`, which can be used to monitor or manage the + /// upload. @objc(putFile:metadata:completion:) @discardableResult open func putFile(from fileURL: URL, metadata: StorageMetadata? = nil, @@ -205,17 +187,17 @@ import Foundation // MARK: - Downloads - /** - * Asynchronously downloads the object at the `StorageReference` to a `Data` instance in memory. - * A `Data` buffer of the provided max size will be allocated, so ensure that the device has enough free - * memory to complete the download. For downloading large files, `write(toFile:)` may be a better option. - * - Parameters: - * - maxSize: The maximum size in bytes to download. If the download exceeds this size, - * the task will be cancelled and an error will be returned. - * - completion: A completion block that either returns the object data on success, - * or an error on failure. - * - Returns: An `StorageDownloadTask` that can be used to monitor or manage the download. - */ + /// Asynchronously downloads the object at the `StorageReference` to a `Data` instance in memory. + /// A `Data` buffer of the provided max size will be allocated, so ensure that the device has + /// enough free + /// memory to complete the download. For downloading large files, `write(toFile:)` may be a better + /// option. + /// - Parameters: + /// - maxSize: The maximum size in bytes to download. If the download exceeds this size, + /// the task will be cancelled and an error will be returned. + /// - completion: A completion block that either returns the object data on success, + /// or an error on failure. + /// - Returns: A `StorageDownloadTask` that can be used to monitor or manage the download. @objc(dataWithMaxSize:completion:) @discardableResult open func getData(maxSize: Int64, completion: @escaping ((_: Data?, _: Error?) -> Void)) -> StorageDownloadTask { @@ -253,13 +235,11 @@ import Foundation return task } - /** - * 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. - * - Parameter completion A completion block that either returns the URL on success, - * or an error on failure. - */ + /// 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. + /// - Parameter completion: A completion block that either returns the URL on success, + /// or an error on failure. @objc(downloadURLWithCompletion:) open func downloadURL(completion: @escaping ((_: URL?, _: Error?) -> Void)) { let fetcherService = storage.fetcherServiceForApp @@ -270,13 +250,11 @@ import Foundation task.enqueue() } - /** - * 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. - * - Throws: An error if the download URL could not be retrieved. - * - Returns: The URL on success. - */ + /// 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. + /// - Throws: An error if the download URL could not be retrieved. + /// - Returns: The URL on success. @available(iOS 13, tvOS 13, macOS 10.15, watchOS 8, *) open func downloadURL() async throws -> URL { return try await withCheckedThrowingContinuation { continuation in @@ -286,25 +264,22 @@ import Foundation } } - /** - * Asynchronously downloads the object at the current path to a specified system filepath. - * - Parameter fileURL A file system URL representing the path the object should be downloaded to. - * - Returns An `StorageDownloadTask` that can be used to monitor or manage the download. - */ + /// Asynchronously downloads the object at the current path to a specified system filepath. + /// - Parameter fileURL: A file system URL representing the path the object should be downloaded + /// to. + /// - Returns A `StorageDownloadTask` that can be used to monitor or manage the download. @objc(writeToFile:) @discardableResult open func write(toFile fileURL: URL) -> StorageDownloadTask { return write(toFile: fileURL, completion: nil) } - /** - * Asynchronously downloads the object at the current path to a specified system filepath. - * - Parameters: - * - fileURL: A file system URL representing the path the object should be downloaded to. - * - completion: A closure that fires when the file download completes, passed either - * a URL pointing to the file path of the downloaded file on success, - * or an error on failure. - * - Returns: A `StorageDownloadTask` that can be used to monitor or manage the download. - */ + /// Asynchronously downloads the object at the current path to a specified system filepath. + /// - Parameters: + /// - fileURL: A file system URL representing the path the object should be downloaded to. + /// - completion: A closure that fires when the file download completes, passed either + /// a URL pointing to the file path of the downloaded file on success, + /// or an error on failure. + /// - Returns: A `StorageDownloadTask` that can be used to monitor or manage the download. @objc(writeToFile:completion:) @discardableResult open func write(toFile fileURL: URL, completion: ((_: URL?, _: Error?) -> Void)?) -> StorageDownloadTask { @@ -337,18 +312,17 @@ import Foundation // MARK: - List Support - /** - * Lists all items (files) and prefixes (folders) under this `StorageReference`. - * - * This is a helper method for calling `list()` repeatedly until there are no more results. - * Consistency of the result is not guaranteed if objects are inserted or removed while this - * operation is executing. All results are buffered in memory. - * - * `listAll(completion:)` is only available for projects using Firebase Rules Version 2. - * - * - Parameter completion A completion handler that will be invoked with all items and prefixes under - * the current `StorageReference`. - */ + /// Lists all items (files) and prefixes (folders) under this `StorageReference`. + /// + /// This is a helper method for calling `list()` repeatedly until there are no more results. + /// + /// Consistency of the result is not guaranteed if objects are inserted or removed while this + /// operation is executing. All results are buffered in memory. + /// + /// `listAll(completion:)` is only available for projects using Firebase Rules Version 2. + /// - Parameter completion: A completion handler that will be invoked with all items and prefixes + /// under + /// the current `StorageReference`. @objc(listAllWithCompletion:) open func listAll(completion: @escaping ((_: StorageListResult?, _: Error?) -> Void)) { let fetcherService = storage.fetcherServiceForApp @@ -396,18 +370,13 @@ import Foundation task.enqueue() } - /** - * Lists all items (files) and prefixes (folders) under this StorageReference. - * - * This is a helper method for calling list() repeatedly until there are no more results. - * Consistency of the result is not guaranteed if objects are inserted or removed while this - * operation is executing. All results are buffered in memory. - * - * `listAll()` is only available for projects using Firebase Rules Version 2. - * - * - Throws: An error if the list operation failed. - * - Returns: All items and prefixes under the current `StorageReference`. - */ + /// Lists all items (files) and prefixes (folders) under this StorageReference. + /// This is a helper method for calling list() repeatedly until there are no more results. + /// Consistency of the result is not guaranteed if objects are inserted or removed while this + /// operation is executing. All results are buffered in memory. + /// `listAll()` is only available for projects using Firebase Rules Version 2. + /// - Throws: An error if the list operation failed. + /// - Returns: All items and prefixes under the current `StorageReference`. @available(iOS 13, tvOS 13, macOS 10.15, watchOS 8, *) open func listAll() async throws -> StorageListResult { return try await withCheckedThrowingContinuation { continuation in @@ -417,21 +386,18 @@ import Foundation } } - /** - * List up to `maxResults` items (files) and prefixes (folders) under this StorageReference. - * - * "/" is treated as a path delimiter. Firebase Storage does not support unsupported object - * paths that end with "/" or contain two consecutive "/"s. All invalid objects in GCS will be - * filtered. - * - * `list(maxResults:completion:)` is only available for projects using Firebase Rules Version 2. - * - * - Parameters: - * - 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 up to `maxResults` items and - * prefixes under the current `StorageReference`. - */ + /// List up to `maxResults` items (files) and prefixes (folders) under this StorageReference. + /// + /// "/" is treated as a path delimiter. Firebase Storage does not support unsupported object + /// paths that end with "/" or contain two consecutive "/"s. All invalid objects in GCS will be + /// filtered. + /// + /// Only available for projects using Firebase Rules Version 2. + /// - Parameters: + /// - 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 up to `maxResults` items and + /// prefixes under the current `StorageReference`. @objc(listWithMaxResults:completion:) open func list(maxResults: Int64, completion: @escaping ((_: StorageListResult?, _: Error?) -> Void)) { @@ -453,24 +419,22 @@ import Foundation } } - /** - * Resumes a previous call to `list(maxResults:completion:)`, starting after a pagination token. - * Returns the next set of items (files) and prefixes (folders) under this `StorageReference`. - * - * "/" is treated as a path delimiter. Storage does not support unsupported object - * paths that end with "/" or contain two consecutive "/"s. All invalid objects in GCS will be - * filtered. - * - * `list(maxResults:pageToken:completion:)`is only available for projects using Firebase Rules - * Version 2. - * - * - Parameters: - * - 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 prefixes - * under the current StorageReference. - */ + /// Resumes a previous call to `list(maxResults:completion:)`, starting after a pagination token. + /// + /// Returns the next set of items (files) and prefixes (folders) under this `StorageReference`. + /// + /// "/" is treated as a path delimiter. Storage does not support unsupported object + /// paths that end with "/" or contain two consecutive "/"s. All invalid objects in GCS will be + /// filtered. + /// + /// `list(maxResults:pageToken:completion:)`is only available for projects using Firebase Rules + /// Version 2. + /// - Parameters: + /// - 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 prefixes + /// under the current StorageReference. @objc(listWithMaxResults:pageToken:completion:) open func list(maxResults: Int64, pageToken: String, @@ -495,11 +459,9 @@ import Foundation // MARK: - Metadata Operations - /** - * Retrieves metadata associated with an object at the current path. - * - Parameter completion A completion block which returns the object metadata on success, - * or an error on failure. - */ + /// Retrieves metadata associated with an object at the current path. + /// - Parameter completion: A completion block which returns the object metadata on success, + /// or an error on failure. @objc(metadataWithCompletion:) open func getMetadata(completion: @escaping ((_: StorageMetadata?, _: Error?) -> Void)) { let fetcherService = storage.fetcherServiceForApp @@ -510,11 +472,9 @@ import Foundation task.enqueue() } - /** - * Retrieves metadata associated with an object at the current path. - * - Throws: An error if the object metadata could not be retrieved. - * - Returns: The object metadata on success. - */ + /// Retrieves metadata associated with an object at the current path. + /// - Throws: An error if the object metadata could not be retrieved. + /// - Returns: The object metadata on success. @available(iOS 13, tvOS 13, macOS 10.15, watchOS 8, *) open func getMetadata() async throws -> StorageMetadata { return try await withCheckedThrowingContinuation { continuation in @@ -524,13 +484,11 @@ import Foundation } } - /** - * 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 the `StorageMetadata` on success, - * or an error on failure. - */ + /// 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 the `StorageMetadata` on success, + /// or an error on failure. @objc(updateMetadata:completion:) open func updateMetadata(_ metadata: StorageMetadata, completion: ((_: StorageMetadata?, _: Error?) -> Void)?) { @@ -543,12 +501,10 @@ import Foundation task.enqueue() } - /** - * Updates the metadata associated with an object at the current path. - * - Parameter metadata A `StorageMetadata` object with the metadata to update. - * - Throws: An error if the metadata update operation failed. - * - Returns: The object metadata on success. - */ + /// Updates the metadata associated with an object at the current path. + /// - Parameter metadata: A `StorageMetadata` object with the metadata to update. + /// - Throws: An error if the metadata update operation failed. + /// - Returns: The object metadata on success. @available(iOS 13, tvOS 13, macOS 10.15, watchOS 8, *) open func updateMetadata(_ metadata: StorageMetadata) async throws -> StorageMetadata { return try await withCheckedThrowingContinuation { continuation in @@ -560,10 +516,8 @@ import Foundation // MARK: - Delete - /** - * Deletes the object at the current path. - * - Parameter completion A completion block which returns a nonnull error on failure. - */ + /// Deletes the object at the current path. + /// - Parameter completion: A completion block which returns a nonnull error on failure. @objc(deleteWithCompletion:) open func delete(completion: ((_: Error?) -> Void)?) { let fetcherService = storage.fetcherServiceForApp @@ -574,10 +528,8 @@ import Foundation task.enqueue() } - /** - * Deletes the object at the current path. - * - Throws: An error if the delete operation failed. - */ + /// Deletes the object at the current path. + /// - Throws: An error if the delete operation failed. @available(iOS 13, tvOS 13, macOS 10.15, watchOS 8, *) open func delete() async throws { return try await withCheckedThrowingContinuation { continuation in @@ -593,10 +545,12 @@ import Foundation // MARK: - NSObject overrides + /// NSObject override @objc override open func copy() -> Any { return StorageReference(storage: storage, path: path) } + /// NSObject override @objc override open func isEqual(_ object: Any?) -> Bool { guard let ref = object as? StorageReference else { return false @@ -604,19 +558,19 @@ import Foundation return storage == ref.storage && path == ref.path } + /// NSObject override @objc override public var hash: Int { return storage.hash ^ path.bucket.hashValue } + /// NSObject override @objc override public var description: String { return "gs://\(path.bucket)/\(path.object ?? "")" } // MARK: - Internal APIs - /** - * The current path which points to an object in the Google Cloud Storage bucket. - */ + /// The current path which points to an object in the Google Cloud Storage bucket. let path: StoragePath override init() { @@ -630,9 +584,7 @@ import Foundation self.path = path } - /** - * For maxSize API, return an error if the size is exceeded. - */ + /// For maxSize API, return an error if the size is exceeded. private func checkSizeOverflow(task: StorageTask, maxSize: Int64) -> NSError? { if task.progress.totalUnitCount > maxSize || task.progress.completedUnitCount > maxSize { return StorageErrorCode.error(withCode: .downloadSizeExceeded, diff --git a/FirebaseStorage/Sources/StorageTask.swift b/FirebaseStorage/Sources/StorageTask.swift index 521beabeaaa..fe119c05c92 100644 --- a/FirebaseStorage/Sources/StorageTask.swift +++ b/FirebaseStorage/Sources/StorageTask.swift @@ -24,6 +24,7 @@ import Foundation * A superclass to all Storage tasks, including `StorageUploadTask` * and `StorageDownloadTask`, to provide state transitions, event raising, and common storage * for metadata and errors. + * * Callbacks are always fired on the developer-specified callback queue. * If no queue is specified, it defaults to the main queue. * This class is thread-safe. @@ -98,6 +99,7 @@ import Foundation /** * Defines task operations such as pause, resume, cancel, and enqueue for all tasks. + * * All tasks are required to implement enqueue, which begins the task, and may optionally * implement pause, resume, and cancel, which operate on the task to pause, resume, and cancel * operations. diff --git a/FirebaseStorage/Sources/StorageUploadTask.swift b/FirebaseStorage/Sources/StorageUploadTask.swift index 77e01f83cc4..759fd6b47c5 100644 --- a/FirebaseStorage/Sources/StorageUploadTask.swift +++ b/FirebaseStorage/Sources/StorageUploadTask.swift @@ -22,10 +22,13 @@ import Foundation /** * `StorageUploadTask` implements resumable uploads to a file in Firebase Storage. + * * Uploads can be returned on completion with a completion callback, and can be monitored * by attaching observers, or controlled by calling `pause()`, `resume()`, * or `cancel()`. + * * Uploads can be initialized from `Data` in memory, or a URL to a file on disk. + * * Uploads are performed on a background queue, and callbacks are raised on the developer * specified `callbackQueue` in Storage, or the main queue if unspecified. */