Fix doc formatting (#4147)

Author: hsubox76

packages/firebase/index.d.ts

@@ -485,7 +485,7 @@ declare namespace firebase {
     linkWithRedirect(provider: firebase.auth.AuthProvider): Promise<void>;
     metadata: firebase.auth.UserMetadata;
     /**
-     * The {@link firebase.User.MultiFactor} object corresponding to the current user.
+     * The {@link firebase.User.MultiFactorUser} object corresponding to the current user.
      * This is used to access all multi-factor properties and operations related to the
      * current user.
      */
@@ -1964,7 +1964,7 @@ declare namespace firebase.auth {
      * For the REVERT_SECOND_FACTOR_ADDITION action, which allows a user to unenroll
      * a newly added second factor, this object contains a `multiFactorInfo` field with
      * the information about the second factor. For phone second factor, the
-     * `multiFactorInfo` is a {@link firebase.auth.Auth.PhoneMultiFactorInfo} object,
+     * `multiFactorInfo` is a {@link firebase.auth.PhoneMultiFactorInfo} object,
      * which contains the phone number.
      */
     data: {
@@ -3323,8 +3323,8 @@ declare namespace firebase.auth {
   /**
    * An authentication error.
    * For method-specific error codes, refer to the specific methods in the
-   * documentation. For common error codes, check the reference below. Use {@link
-   * firebase.auth.Error#code} to get the specific error code. For a detailed
+   * documentation. For common error codes, check the reference below. Use{@link
+   * firebase.auth.Error.code} to get the specific error code. For a detailed
    * message, use {@link firebase.auth.Error.message}.
    * Errors with the code <strong>auth/account-exists-with-different-credential
    * </strong> will have the additional fields <strong>email</strong> and <strong>
@@ -3452,7 +3452,7 @@ declare namespace firebase.auth {
     phoneNumber?: string;
     /**
      * The tenant ID being used for sign-in/linking. If you use
-     * {@link firebase.auth.signInWithRedirect} to sign in, you have to
+     * {@link firebase.auth.Auth.signInWithRedirect} to sign in, you have to
      * set the tenant ID on Auth instanace again as the tenant ID is not
      * persisted after redirection.
      */
@@ -7534,18 +7534,18 @@ declare namespace firebase.storage {
      * @param url A URL in the form: <br />
      *     1) a gs:// URL, for example `gs://bucket/files/image.png` <br />
      *     2) a download URL taken from object metadata. <br />
-     *     @see {@link firebase.storage.FullMetadata.prototype.downloadURLs}
+     *     @see {@link firebase.storage.FullMetadata.downloadURLs}
      * @return A reference for the given URL.
      */
     refFromURL(url: string): firebase.storage.Reference;
     /**
      * @param time The new maximum operation retry time in milliseconds.
-     * @see {@link firebase.storage.Storage.prototype.maxOperationRetryTime}
+     * @see {@link firebase.storage.Storage.maxOperationRetryTime}
      */
     setMaxOperationRetryTime(time: number): any;
     /**
      * @param time The new maximum upload retry time in milliseconds.
-     * @see {@link firebase.storage.Storage.prototype.maxUploadRetryTime}
+     * @see {@link firebase.storage.Storage.maxUploadRetryTime}
      */
     setMaxUploadRetryTime(time: number): any;
   }
@@ -7593,7 +7593,7 @@ declare namespace firebase.storage {
   /**
    * An event that is triggered on a task.
    * @enum {string}
-   * @see {@link firebase.storage.UploadTask.prototype.on}
+   * @see {@link firebase.storage.UploadTask.on}
    */
   type TaskEvent = string;
   var TaskEvent: {

scripts/docgen/content-sources/js/toc.yaml

@@ -67,31 +67,31 @@ toc:
   - title: "IdTokenResult"
     path: /docs/reference/js/firebase.auth.IDTokenResult
   - title: "MultiFactorAssertion"
-    path: /docs/reference/js/firebase.auth.multifactorassertion
+    path: /docs/reference/js/firebase.auth.MultiFactorAssertion
   - title: "MultiFactorError"
-    path: /docs/reference/js/firebase.auth.multifactorerror
+    path: /docs/reference/js/firebase.auth.MultiFactorError
   - title: "MultiFactorInfo"
-    path: /docs/reference/js/firebase.auth.multifactorinfo
+    path: /docs/reference/js/firebase.auth.MultiFactorInfo
   - title: "MultiFactorResolver"
-    path: /docs/reference/js/firebase.auth.multifactorresolver
+    path: /docs/reference/js/firebase.auth.MultiFactorResolver
   - title: "MultiFactorSession"
-    path: /docs/reference/js/firebase.auth.multifactorsession
+    path: /docs/reference/js/firebase.auth.MultiFactorSession
   - title: "PhoneAuthCredential"
-    path: /docs/reference/js/firebase.auth.phoneauthcredential
+    path: /docs/reference/js/firebase.auth.PhoneAuthCredential
   - title: "PhoneMultiFactorAssertion"
-    path: /docs/reference/js/firebase.auth.phonemultifactorassertion
+    path: /docs/reference/js/firebase.auth.PhoneMultiFactorAssertion
   - title: "PhoneMultiFactorEnrollInfoOptions"
-    path: /docs/reference/js/firebase.auth.phonemultifactorenrollinfooptions
+    path: /docs/reference/js/firebase.auth.PhoneMultiFactorEnrollInfoOptions
   - title: "PhoneMultiFactorGenerator"
-    path: /docs/reference/js/firebase.auth.phonemultifactorgenerator
+    path: /docs/reference/js/firebase.auth.PhoneMultiFactorGenerator
   - title: "PhoneMultiFactorInfo"
-    path: /docs/reference/js/firebase.auth.phonemultifactorinfo
+    path: /docs/reference/js/firebase.auth.PhoneMultiFactorInfo
   - title: "PhoneMultiFactorSignInInfoOptions"
-    path: /docs/reference/js/firebase.auth.phonemultifactorsignininfooptions
+    path: /docs/reference/js/firebase.auth.PhoneMultiFactorSignInInfoOptions
   - title: "PhoneSingleFactorInfoOptions"
-    path: /docs/reference/js/firebase.auth.phonesinglefactorinfooptions
+    path: /docs/reference/js/firebase.auth.PhoneSingleFactorInfoOptions
   - title: "MultiFactorUser"
-    path: /docs/reference/js/firebase.user.multifactoruser
+    path: /docs/reference/js/firebase.user.MultiFactorUser
   - title: "OAuthCredential"
     path: /docs/reference/js/firebase.auth.OAuthCredential
   - title: "OAuthCredentialOptions"
@@ -236,6 +236,8 @@ toc:
 - title: "firebase.storage"
   path: /docs/reference/js/firebase.storage
   section:
+  - title: "FirebaseStorageError"
+    path: /docs/reference/js/firebase.storage.FirebaseStorageError
   - title: "FullMetadata"
     path: /docs/reference/js/firebase.storage.FullMetadata
   - title: "ListOptions"
@@ -248,6 +250,8 @@ toc:
     path: /docs/reference/js/firebase.storage.SettableMetadata
   - title: "Storage"
     path: /docs/reference/js/firebase.storage.Storage
+  - title: "StorageObserver"
+    path: /docs/reference/js/firebase.storage.StorageObserver
   - title: "UploadMetadata"
     path: /docs/reference/js/firebase.storage.UploadMetadata
   - title: "UploadTask"

scripts/docgen/generate-docs.js

@@ -1,6 +1,6 @@
 /**
  * @license
- * Copyright 2019 Google Inc.
+ * Copyright 2019 Google LLC
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -104,7 +104,22 @@ function fixLinks(file) {
       const re = new RegExp(lower, 'g');
       caseFixedLinks = caseFixedLinks.replace(re, lowerToUpperLookup[lower]);
     }
-    return fs.writeFile(file, caseFixedLinks);
+    let badLinkCleanup = caseFixedLinks.replace(
+      /{@link (.+)}/g,
+      (all, text) => {
+        // It's expected to have some broken @link tags in Node docs
+        // since they could reference some pages only generated for JS.
+        // Just render as plain text. Warn if it's not a Node doc.
+        if (!file.includes('/node/')) {
+          console.log(
+            `Unable to generate link for "${all} in ${file}", ` +
+              `removing markup and rendering as plain text.`
+          );
+        }
+        return text;
+      }
+    );
+    return fs.writeFile(file, badLinkCleanup);
   });
 }