chore: Updated API reference comments to tsdoc.org standards (#1242)

* chore: Updated API reference comments to tsdoc.org standards

* chore: Removed more old jsdoc syntax

Author: hiranya911

etc/firebase-admin.messaging.api.md

@@ -180,7 +180,6 @@ export type Message = TokenMessage | TopicMessage | ConditionMessage;
 
 // @public
 export class Messaging {
-    constructor(app: App);
     get app(): App;
     send(message: Message, dryRun?: boolean): Promise<string>;
     sendAll(messages: Message[], dryRun?: boolean): Promise<BatchResponse>;

src/app/core.ts

@@ -20,29 +20,30 @@ import { Agent } from 'http';
 import { Credential } from './credential';
 
 /**
- * Available options to pass to [`initializeApp()`](admin#.initializeApp).
+ * Available options to pass to {@link firebase-admin.app#initializeApp}.
  */
 export interface AppOptions {
 
   /**
    * A {@link Credential `Credential`} object used to
    * authenticate the Admin SDK.
    *
-   * See [Initialize the SDK](/docs/admin/setup#initialize_the_sdk) for detailed
-   * documentation and code samples.
+   * See {@link https://firebase.google.com/docs/admin/setup#initialize_the_sdk | Initialize the SDK}
+   * for detailed documentation and code samples.
    */
   credential?: Credential;
 
   /**
-   * The object to use as the [`auth`](/docs/reference/security/database/#auth)
+   * The object to use as the {@link https://firebase.google.com/docs/reference/security/database/#auth | auth}
    * variable in your Realtime Database Rules when the Admin SDK reads from or
    * writes to the Realtime Database. This allows you to downscope the Admin SDK
    * from its default full read and write privileges.
    *
    * You can pass `null` to act as an unauthenticated client.
    *
    * See
-   * [Authenticate with limited privileges](/docs/database/admin/start#authenticate-with-limited-privileges)
+   * {@link https://firebase.google.com/docs/database/admin/start#authenticate-with-limited-privileges |
+   * Authenticate with limited privileges}
    * for detailed documentation and code samples.
    */
   databaseAuthVariableOverride?: object | null;
@@ -71,7 +72,7 @@ export interface AppOptions {
   projectId?: string;
 
   /**
-   * An [HTTP Agent](https://nodejs.org/api/http.html#http_class_http_agent)
+   * An {@link https://nodejs.org/api/http.html#http_class_http_agent | HTTP Agent}
    * to be used when making outgoing HTTP calls. This Agent instance is used
    * by all services that make REST calls (e.g. `auth`, `messaging`,
    * `projectManagement`).
@@ -87,12 +88,6 @@ export interface AppOptions {
 /**
  * A Firebase app holds the initialization information for a collection of
  * services.
- *
- * Do not call this constructor directly. Instead, use
- * {@link
- *   https://firebase.google.com/docs/reference/admin/node/admin#.initializeApp
- *   `admin.initializeApp()`}
- * to create an app.
  */
 export interface App {
 
@@ -119,10 +114,7 @@ export interface App {
 
   /**
    * The (read-only) configuration options for this app. These are the original
-   * parameters given in
-   * {@link
-   *   https://firebase.google.com/docs/reference/admin/node/admin#.initializeApp
-   *   `admin.initializeApp()`}.
+   * parameters given in {@link firebase-admin.app#initializeApp}.
    *
    * @example
    * ```javascript
@@ -170,7 +162,9 @@ export interface FirebaseError {
   stack?: string;
 
   /**
-   * @return A JSON-serializable representation of this object.
+   * Returns a JSON-serializable object representation of this error.
+   *
+   * @returns A JSON-serializable representation of this object.
    */
   toJSON(): object;
 }

src/app/credential-factory.ts

@@ -28,22 +28,16 @@ const globalRefreshTokenCreds: { [key: string]: RefreshTokenCredential } = {};
 
 /**
  * Returns a credential created from the
- * {@link
- *    https://developers.google.com/identity/protocols/application-default-credentials
- *    Google Application Default Credentials}
+ * {@link https://developers.google.com/identity/protocols/application-default-credentials |
+ * Google Application Default Credentials}
  * that grants admin access to Firebase services. This credential can be used
- * in the call to
- * {@link
- *   https://firebase.google.com/docs/reference/admin/node/admin#.initializeApp
- *  `admin.initializeApp()`}.
+ * in the call to {@link firebase-admin.app#initializeApp}.
  *
  * Google Application Default Credentials are available on any Google
  * infrastructure, such as Google App Engine and Google Compute Engine.
  *
  * See
- * {@link
- *   https://firebase.google.com/docs/admin/setup#initialize_the_sdk
- *   Initialize the SDK}
+ * {@link https://firebase.google.com/docs/admin/setup#initialize_the_sdk | Initialize the SDK}
  * for more details.
  *
  * @example
@@ -54,10 +48,10 @@ const globalRefreshTokenCreds: { [key: string]: RefreshTokenCredential } = {};
  * });
  * ```
  *
- * @param httpAgent Optional [HTTP Agent](https://nodejs.org/api/http.html#http_class_http_agent)
+ * @param httpAgent Optional {@link https://nodejs.org/api/http.html#http_class_http_agent | HTTP Agent}
  *   to be used when retrieving access tokens from Google token servers.
  *
- * @return A credential authenticated via Google
+ * @returns A credential authenticated via Google
  *   Application Default Credentials that can be used to initialize an app.
  */
 export function applicationDefault(httpAgent?: Agent): Credential {
@@ -70,15 +64,10 @@ export function applicationDefault(httpAgent?: Agent): Credential {
 /**
  * Returns a credential created from the provided service account that grants
  * admin access to Firebase services. This credential can be used in the call
- * to
- * {@link
- *   https://firebase.google.com/docs/reference/admin/node/admin#.initializeApp
- *   `admin.initializeApp()`}.
+ * to {@link firebase-admin.app#initializeApp}.
  *
  * See
- * {@link
- *   https://firebase.google.com/docs/admin/setup#initialize_the_sdk
- *   Initialize the SDK}
+ * {@link https://firebase.google.com/docs/admin/setup#initialize_the_sdk | Initialize the SDK}
  * for more details.
  *
  * @example
@@ -106,10 +95,10 @@ export function applicationDefault(httpAgent?: Agent): Credential {
  *
  * @param serviceAccountPathOrObject The path to a service
  *   account key JSON file or an object representing a service account key.
- * @param httpAgent Optional [HTTP Agent](https://nodejs.org/api/http.html#http_class_http_agent)
+ * @param httpAgent Optional {@link https://nodejs.org/api/http.html#http_class_http_agent | HTTP Agent}
  *   to be used when retrieving access tokens from Google token servers.
  *
- * @return A credential authenticated via the
+ * @returns A credential authenticated via the
  *   provided service account that can be used to initialize an app.
  */
 export function cert(serviceAccountPathOrObject: string | ServiceAccount, httpAgent?: Agent): Credential {
@@ -124,15 +113,10 @@ export function cert(serviceAccountPathOrObject: string | ServiceAccount, httpAg
 /**
  * Returns a credential created from the provided refresh token that grants
  * admin access to Firebase services. This credential can be used in the call
- * to
- * {@link
- *   https://firebase.google.com/docs/reference/admin/node/admin#.initializeApp
- *   `admin.initializeApp()`}.
+ * to {@link firebase-admin.app#initializeApp}.
  *
  * See
- * {@link
- *   https://firebase.google.com/docs/admin/setup#initialize_the_sdk
- *   Initialize the SDK}
+ * {@link https://firebase.google.com/docs/admin/setup#initialize_the_sdk | Initialize the SDK}
  * for more details.
  *
  * @example
@@ -148,10 +132,10 @@ export function cert(serviceAccountPathOrObject: string | ServiceAccount, httpAg
  * @param refreshTokenPathOrObject The path to a Google
  *   OAuth2 refresh token JSON file or an object representing a Google OAuth2
  *   refresh token.
- * @param httpAgent Optional [HTTP Agent](https://nodejs.org/api/http.html#http_class_http_agent)
+ * @param httpAgent Optional {@link https://nodejs.org/api/http.html#http_class_http_agent | HTTP Agent}
  *   to be used when retrieving access tokens from Google token servers.
  *
- * @return A credential authenticated via the
+ * @returns A credential authenticated via the
  *   provided service account that can be used to initialize an app.
  */
 export function refreshToken(refreshTokenPathOrObject: string | object, httpAgent?: Agent): Credential {

src/app/credential.ts

@@ -42,12 +42,7 @@ export interface Credential {
    * Returns a Google OAuth2 access token object used to authenticate with
    * Firebase services.
    *
-   * This object contains the following properties:
-   * * `access_token` (`string`): The actual Google OAuth2 access token.
-   * * `expires_in` (`number`): The number of seconds from when the token was
-   *   issued that it expires.
-   *
-   * @return A Google OAuth2 access token object.
+   * @returns A Google OAuth2 access token object.
    */
   getAccessToken(): Promise<GoogleOAuthAccessToken>;
 }

src/app/firebase-app.ts

@@ -192,7 +192,7 @@ export class FirebaseApp implements app.App {
   /**
    * Returns the Auth service instance associated with this app.
    *
-   * @return The Auth service instance of this app.
+   * @returns The Auth service instance of this app.
    */
   public auth(): Auth {
     const fn = require('../auth/index').getAuth;
@@ -202,7 +202,7 @@ export class FirebaseApp implements app.App {
   /**
    * Returns the Database service for the specified URL, and the current app.
    *
-   * @return The Database service instance of this app.
+   * @returns The Database service instance of this app.
    */
   public database(url?: string): Database {
     const fn = require('../database/index').getDatabaseWithUrl;
@@ -212,7 +212,7 @@ export class FirebaseApp implements app.App {
   /**
    * Returns the Messaging service instance associated with this app.
    *
-   * @return The Messaging service instance of this app.
+   * @returns The Messaging service instance of this app.
    */
   public messaging(): Messaging {
     const fn = require('../messaging/index').getMessaging;
@@ -222,7 +222,7 @@ export class FirebaseApp implements app.App {
   /**
    * Returns the Storage service instance associated with this app.
    *
-   * @return The Storage service instance of this app.
+   * @returns The Storage service instance of this app.
    */
   public storage(): Storage {
     const fn = require('../storage/index').getStorage;
@@ -237,7 +237,7 @@ export class FirebaseApp implements app.App {
   /**
    * Returns the InstanceId service instance associated with this app.
    *
-   * @return The InstanceId service instance of this app.
+   * @returns The InstanceId service instance of this app.
    */
   public instanceId(): InstanceId {
     const fn = require('../instance-id/index').getInstanceId;
@@ -247,7 +247,7 @@ export class FirebaseApp implements app.App {
   /**
    * Returns the MachineLearning service instance associated with this app.
    *
-   * @return The Machine Learning service instance of this app
+   * @returns The Machine Learning service instance of this app
    */
   public machineLearning(): MachineLearning {
     const fn = require('../machine-learning/index').getMachineLearning;
@@ -257,7 +257,7 @@ export class FirebaseApp implements app.App {
   /**
    * Returns the ProjectManagement service instance associated with this app.
    *
-   * @return The ProjectManagement service instance of this app.
+   * @returns The ProjectManagement service instance of this app.
    */
   public projectManagement(): ProjectManagement {
     const fn = require('../project-management/index').getProjectManagement;
@@ -267,7 +267,7 @@ export class FirebaseApp implements app.App {
   /**
    * Returns the SecurityRules service instance associated with this app.
    *
-   * @return The SecurityRules service instance of this app.
+   * @returns The SecurityRules service instance of this app.
    */
   public securityRules(): SecurityRules {
     const fn = require('../security-rules/index').getSecurityRules;
@@ -277,7 +277,7 @@ export class FirebaseApp implements app.App {
   /**
    * Returns the RemoteConfig service instance associated with this app.
    *
-   * @return The RemoteConfig service instance of this app.
+   * @returns The RemoteConfig service instance of this app.
    */
   public remoteConfig(): RemoteConfig {
     const fn = require('../remote-config/index').getRemoteConfig;
@@ -287,7 +287,7 @@ export class FirebaseApp implements app.App {
   /**
    * Returns the name of the FirebaseApp instance.
    *
-   * @return The name of the FirebaseApp instance.
+   * @returns The name of the FirebaseApp instance.
    */
   get name(): string {
     this.checkDestroyed_();
@@ -297,7 +297,7 @@ export class FirebaseApp implements app.App {
   /**
    * Returns the options for the FirebaseApp instance.
    *
-   * @return The options for the FirebaseApp instance.
+   * @returns The options for the FirebaseApp instance.
    */
   get options(): AppOptions {
     this.checkDestroyed_();
@@ -314,7 +314,7 @@ export class FirebaseApp implements app.App {
   /**
    * Deletes the FirebaseApp instance.
    *
-   * @return An empty Promise fulfilled once the FirebaseApp instance is deleted.
+   * @returns An empty Promise fulfilled once the FirebaseApp instance is deleted.
    */
   public delete(): Promise<void> {
     this.checkDestroyed_();

src/app/firebase-namespace.ts

@@ -72,7 +72,7 @@ export class FirebaseNamespaceInternals {
    *   to a file.
    * @param appName Optional name of the FirebaseApp instance.
    *
-   * @return A new App instance.
+   * @returns A new App instance.
    */
   public initializeApp(options?: AppOptions, appName = DEFAULT_APP_NAME): App {
     if (typeof options === 'undefined') {
@@ -114,7 +114,7 @@ export class FirebaseNamespaceInternals {
    * if no name is provided).
    *
    * @param appName Optional name of the FirebaseApp instance to return.
-   * @return The App instance which has the provided name.
+   * @returns The App instance which has the provided name.
    */
   public app(appName = DEFAULT_APP_NAME): App {
     if (typeof appName !== 'string' || appName === '') {
@@ -360,7 +360,7 @@ export class FirebaseNamespace {
    *   otherwise it will be assumed to be pointing to a file.
    * @param appName Optional name of the FirebaseApp instance.
    *
-   * @return A new FirebaseApp instance.
+   * @returns A new FirebaseApp instance.
    */
   public initializeApp(options?: AppOptions, appName?: string): App {
     return this.INTERNAL.initializeApp(options, appName);
@@ -371,7 +371,7 @@ export class FirebaseNamespace {
    * if no name is provided).
    *
    * @param appName Optional name of the FirebaseApp instance to return.
-   * @return The FirebaseApp instance which has the provided name.
+   * @returns The FirebaseApp instance which has the provided name.
    */
   public app(appName?: string): App {
     return this.INTERNAL.app(appName);

src/auth/action-code-settings-builder.ts

@@ -223,7 +223,7 @@ export class ActionCodeSettingsBuilder {
    * Returns the corresponding constructed server request corresponding to the
    * current ActionCodeSettings.
    *
-   * @return {EmailActionCodeRequest} The constructed EmailActionCodeRequest request.
+   * @returns The constructed EmailActionCodeRequest request.
    */
   public buildRequest(): EmailActionCodeRequest {
     const request: { [key: string]: any } = {