Several minor doc fixes for Functions (#12323)

Author: paulb777

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<Request: Encodable, Response: Decodable> {
   /// The timeout to use when calling the function. Defaults to 60 seconds.
   public var timeoutInterval: TimeInterval {

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 {

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.

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<Any>`. 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<Any>`. 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