From 6b0cc0276cef38f7bdf056923d4785cfc48a5077 Mon Sep 17 00:00:00 2001 From: Paul Beusterien Date: Mon, 29 Jan 2024 09:43:20 -0800 Subject: [PATCH] Several minor doc fixes for Functions (#12323) --- .../Sources/Callable+Codable.swift | 2 +- FirebaseFunctions/Sources/Functions.swift | 75 +++++------ .../Sources/FunctionsError.swift | 2 +- FirebaseFunctions/Sources/HTTPSCallable.swift | 118 ++++++++---------- 4 files changed, 89 insertions(+), 108 deletions(-) diff --git a/FirebaseFunctions/Sources/Callable+Codable.swift b/FirebaseFunctions/Sources/Callable+Codable.swift index 559b9846ce4..5a8e508a9f0 100644 --- a/FirebaseFunctions/Sources/Callable+Codable.swift +++ b/FirebaseFunctions/Sources/Callable+Codable.swift @@ -15,7 +15,7 @@ import FirebaseSharedSwift import Foundation -// A `Callable` is reference to a particular Callable HTTPS trigger in Cloud Functions. +/// A `Callable` is reference to a particular Callable HTTPS trigger in Cloud Functions. public struct Callable { /// The timeout to use when calling the function. Defaults to 60 seconds. public var timeoutInterval: TimeInterval { diff --git a/FirebaseFunctions/Sources/Functions.swift b/FirebaseFunctions/Sources/Functions.swift index 61d00d5e040..14eeb4e4f1b 100644 --- a/FirebaseFunctions/Sources/Functions.swift +++ b/FirebaseFunctions/Sources/Functions.swift @@ -38,9 +38,7 @@ enum FunctionsConstants { static let defaultRegion = "us-central1" } -/** - * `Functions` is the client for Cloud Functions for a Firebase project. - */ +/// `Functions` is the client for Cloud Functions for a Firebase project. @objc(FIRFunctions) open class Functions: NSObject { // MARK: - Private Variables @@ -61,15 +59,12 @@ enum FunctionsConstants { // MARK: - Public APIs - /** - * The current emulator origin, or `nil` if it is not set. - */ + /// The current emulator origin, or `nil` if it is not set. open private(set) var emulatorOrigin: String? - /** - * Creates a Cloud Functions client using the default or returns a pre-existing instance if it already exists. - * - Returns: A shared Functions instance initialized with the default `FirebaseApp`. - */ + /// Creates a Cloud Functions client using the default or returns a pre-existing instance if it + /// already exists. + /// - Returns: A shared Functions instance initialized with the default `FirebaseApp`. @objc(functions) open class func functions() -> Functions { return functions( app: FirebaseApp.app(), @@ -78,57 +73,51 @@ enum FunctionsConstants { ) } - /** - * Creates a Cloud Functions client with the given app, or returns a pre-existing - * instance if one already exists. - * - Parameter app The app for the Firebase project. - * - Returns: A shared Functions instance initialized with the specified `FirebaseApp`. - */ + /// Creates a Cloud Functions client with the given app, or returns a pre-existing + /// instance if one already exists. + /// - Parameter app: The app for the Firebase project. + /// - Returns: A shared Functions instance initialized with the specified `FirebaseApp`. @objc(functionsForApp:) open class func functions(app: FirebaseApp) -> Functions { return functions(app: app, region: FunctionsConstants.defaultRegion, customDomain: nil) } - /** - * Creates a Cloud Functions client with the default app and given region. - * - Parameter region The region for the HTTP trigger, such as `us-central1`. - * - Returns: A shared Functions instance initialized with the default `FirebaseApp` and a custom region. - */ + /// Creates a Cloud Functions client with the default app and given region. + /// - Parameter region: The region for the HTTP trigger, such as `us-central1`. + /// - Returns: A shared Functions instance initialized with the default `FirebaseApp` and a + /// custom region. @objc(functionsForRegion:) open class func functions(region: String) -> Functions { return functions(app: FirebaseApp.app(), region: region, customDomain: nil) } - /** - * Creates a Cloud Functions client with the given app and region, or returns a pre-existing - * instance if one already exists. - * - Parameter customDomain A custom domain for the HTTP trigger, such as "https://mydomain.com". - * - Returns: A shared Functions instance initialized with the default `FirebaseApp` and a custom HTTP trigger domain. - */ + /// Creates a Cloud Functions client with the given custom domain or returns a pre-existing + /// instance if one already exists. + /// - Parameter customDomain: A custom domain for the HTTP trigger, such as + /// "https://mydomain.com". + /// - Returns: A shared Functions instance initialized with the default `FirebaseApp` and a + /// custom HTTP trigger domain. @objc(functionsForCustomDomain:) open class func functions(customDomain: String) -> Functions { return functions(app: FirebaseApp.app(), region: FunctionsConstants.defaultRegion, customDomain: customDomain) } - /** - * Creates a Cloud Functions client with the given app and region, or returns a pre-existing - * instance if one already exists. - * - Parameters: - * - app: The app for the Firebase project. - * - region: The region for the HTTP trigger, such as `us-central1`. - * - Returns: An instance of `Functions` with a custom app and region. - */ + /// Creates a Cloud Functions client with the given app and region, or returns a pre-existing + /// instance if one already exists. + /// - Parameters: + /// - app: The app for the Firebase project. + /// - region: The region for the HTTP trigger, such as `us-central1`. + /// - Returns: An instance of `Functions` with a custom app and region. @objc(functionsForApp:region:) open class func functions(app: FirebaseApp, region: String) -> Functions { return functions(app: app, region: region, customDomain: nil) } - /** - * Creates a Cloud Functions client with the given app and region, or returns a pre-existing - * instance if one already exists. - * - Parameters: - * - app The app for the Firebase project. - * - customDomain A custom domain for the HTTP trigger, such as `https://mydomain.com`. - * - Returns: An instance of `Functions` with a custom app and HTTP trigger domain. - */ + /// Creates a Cloud Functions client with the given app and custom domain, or returns a + /// pre-existing + /// instance if one already exists. + /// - Parameters: + /// - app: The app for the Firebase project. + /// - customDomain: A custom domain for the HTTP trigger, such as `https://mydomain.com`. + /// - Returns: An instance of `Functions` with a custom app and HTTP trigger domain. @objc(functionsForApp:customDomain:) open class func functions(app: FirebaseApp, customDomain: String) -> Functions { diff --git a/FirebaseFunctions/Sources/FunctionsError.swift b/FirebaseFunctions/Sources/FunctionsError.swift index 8227d1cd1e0..8af6df9e077 100644 --- a/FirebaseFunctions/Sources/FunctionsError.swift +++ b/FirebaseFunctions/Sources/FunctionsError.swift @@ -14,7 +14,7 @@ import Foundation -/// The error domain for codes in the `FunctionsErrorCode` enum. +/// The error domain for codes in the ``FunctionsErrorCode`` enum. public let FunctionsErrorDomain: String = "com.firebase.functions" /// The key for finding error details in the `NSError` userInfo. diff --git a/FirebaseFunctions/Sources/HTTPSCallable.swift b/FirebaseFunctions/Sources/HTTPSCallable.swift index 5f773d43463..8391d153236 100644 --- a/FirebaseFunctions/Sources/HTTPSCallable.swift +++ b/FirebaseFunctions/Sources/HTTPSCallable.swift @@ -14,18 +14,14 @@ import Foundation -/** - * A `HTTPSCallableResult` contains the result of calling a `HTTPSCallable`. - */ +/// A `HTTPSCallableResult` contains the result of calling a `HTTPSCallable`. @objc(FIRHTTPSCallableResult) open class HTTPSCallableResult: NSObject { - /** - * The data that was returned from the Callable HTTPS trigger. - * - * The data is in the form of native objects. For example, if your trigger returned an - * array, this object would be an `Array`. If your trigger returned a JavaScript object with - * keys and values, this object would be an instance of `[String: Any]`. - */ + /// The data that was returned from the Callable HTTPS trigger. + /// + /// The data is in the form of native objects. For example, if your trigger returned an + /// array, this object would be an `Array`. If your trigger returned a JavaScript object with + /// keys and values, this object would be an instance of `[String: Any]`. @objc public let data: Any init(data: Any) { @@ -54,9 +50,7 @@ open class HTTPSCallable: NSObject { // MARK: - Public Properties - /** - * The timeout to use when calling the function. Defaults to 70 seconds. - */ + /// The timeout to use when calling the function. Defaults to 70 seconds. @objc open var timeoutInterval: TimeInterval = 70 init(functions: Functions, name: String, options: HTTPSCallableOptions? = nil) { @@ -71,28 +65,27 @@ open class HTTPSCallable: NSObject { endpoint = .url(url) } - /** - * Executes this Callable HTTPS trigger asynchronously. - * - * The data passed into the trigger can be any of the following types: - * - `nil` or `NSNull` - * - `String` - * - `NSNumber`, or any Swift numeric type bridgeable to `NSNumber` - * - `[Any]`, where the contained objects are also one of these types. - * - `[String: Any]` where the values are also one of these types. - * - * The request to the Cloud Functions backend made by this method automatically includes a - * Firebase Installations ID token to identify the app instance. If a user is logged in with - * Firebase Auth, an auth ID token for the user is also automatically included. - * - * Firebase Cloud Messaging sends data to the Firebase backend periodically to collect information - * regarding the app instance. To stop this, see `Messaging.deleteData()`. It - * resumes with a new FCM Token the next time you call this method. - * - * - Parameters: - * - data: Parameters to pass to the trigger. - * - completion: The block to call when the HTTPS request has completed. - */ + /// Executes this Callable HTTPS trigger asynchronously. + /// + /// The data passed into the trigger can be any of the following types: + /// - `nil` or `NSNull` + /// - `String` + /// - `NSNumber`, or any Swift numeric type bridgeable to `NSNumber` + /// - `[Any]`, where the contained objects are also one of these types. + /// - `[String: Any]` where the values are also one of these types. + /// + /// The request to the Cloud Functions backend made by this method automatically includes a + /// Firebase Installations ID token to identify the app instance. If a user is logged in with + /// Firebase Auth, an auth ID token for the user is also automatically included. + /// + /// Firebase Cloud Messaging sends data to the Firebase backend periodically to collect + /// information + /// regarding the app instance. To stop this, see `Messaging.deleteData()`. It + /// resumes with a new FCM Token the next time you call this method. + /// + /// - Parameters: + /// - data: Parameters to pass to the trigger. + /// - completion: The block to call when the HTTPS request has completed. @objc(callWithObject:completion:) open func call(_ data: Any? = nil, completion: @escaping (HTTPSCallableResult?, Error?) -> Void) { @@ -121,39 +114,38 @@ open class HTTPSCallable: NSObject { } } - /** - * Executes this Callable HTTPS trigger asynchronously. This API should only be used from Objective-C. - * - * The request to the Cloud Functions backend made by this method automatically includes a - * Firebase Installations ID token to identify the app instance. If a user is logged in with - * Firebase Auth, an auth ID token for the user is also automatically included. - * - * Firebase Cloud Messaging sends data to the Firebase backend periodically to collect information - * regarding the app instance. To stop this, see `Messaging.deleteData()`. It - * resumes with a new FCM Token the next time you call this method. - * - * - Parameter completion The block to call when the HTTPS request has completed. - */ + /// Executes this Callable HTTPS trigger asynchronously. This API should only be used from + /// Objective-C. + /// + /// The request to the Cloud Functions backend made by this method automatically includes a + /// Firebase Installations ID token to identify the app instance. If a user is logged in with + /// Firebase Auth, an auth ID token for the user is also automatically included. + /// + /// Firebase Cloud Messaging sends data to the Firebase backend periodically to collect + /// information + /// regarding the app instance. To stop this, see `Messaging.deleteData()`. It + /// resumes with a new FCM Token the next time you call this method. + /// + /// - Parameter completion: The block to call when the HTTPS request has completed. @objc(callWithCompletion:) public func __call(completion: @escaping (HTTPSCallableResult?, Error?) -> Void) { call(nil, completion: completion) } - /** - * Executes this Callable HTTPS trigger asynchronously. - * - * The request to the Cloud Functions backend made by this method automatically includes a - * FCM token to identify the app instance. If a user is logged in with Firebase - * Auth, an auth ID token for the user is also automatically included. - * - * Firebase Cloud Messaging sends data to the Firebase backend periodically to collect information - * regarding the app instance. To stop this, see `Messaging.deleteData()`. It - * resumes with a new FCM Token the next time you call this method. - * - * - Parameter data Parameters to pass to the trigger. - * - Throws: An error if the Cloud Functions invocation failed. - * - Returns: The result of the call. - */ + /// Executes this Callable HTTPS trigger asynchronously. + /// + /// The request to the Cloud Functions backend made by this method automatically includes a + /// FCM token to identify the app instance. If a user is logged in with Firebase + /// Auth, an auth ID token for the user is also automatically included. + /// + /// Firebase Cloud Messaging sends data to the Firebase backend periodically to collect + /// information + /// regarding the app instance. To stop this, see `Messaging.deleteData()`. It + /// resumes with a new FCM Token the next time you call this method. + /// + /// - Parameter data: Parameters to pass to the trigger. + /// - Throws: An error if the Cloud Functions invocation failed. + /// - Returns: The result of the call. @available(iOS 13, tvOS 13, macOS 10.15, macCatalyst 13, watchOS 7, *) open func call(_ data: Any? = nil) async throws -> HTTPSCallableResult { return try await withCheckedThrowingContinuation { continuation in