Skip to content

Commit

Permalink
Storage docs fixes (#12344)
Browse files Browse the repository at this point in the history
  • Loading branch information
@paulb777
paulb777 authored Feb 1, 2024
1 parent 8ec4afc commit 2d3ecf9
Show file tree
Hide file tree
Showing 10 changed files with 318 additions and 383 deletions.
26 changes: 10 additions & 16 deletions FirebaseStorage/Sources/AsyncAwait.swift
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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,
Expand Down Expand Up @@ -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,
Expand Down Expand Up @@ -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,
Expand Down Expand Up @@ -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
Expand All @@ -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.
Expand Down
35 changes: 19 additions & 16 deletions FirebaseStorage/Sources/Result.swift
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.
///
Expand All @@ -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.

Expand All @@ -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
Expand All @@ -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,
Expand All @@ -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,
Expand All @@ -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) {
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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) {
Expand All @@ -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`.
///
Expand Down
Loading

0 comments on commit 2d3ecf9

Please sign in to comment.