Implement @webonly tag to exclude items from Node docs (#1679)

- Use built-in Typescript AST tools to generate a temporary abridged copy of `index.d.ts` as a source for generating Node documentation.

- `@webonly` tag used to indicate which sections to omit.

- Custom Typedoc theme updated to not display `@webonly` as a tag section in doc output.

- Rearrange signature/description ordering of overloaded methods.

Author: hsubox76

packages/firebase/index.d.ts

@@ -362,6 +362,8 @@ declare namespace firebase {
      *     console.</dd>
      * </dl>
      *
+     * @webonly
+     *
      * @example
      * ```javascript
      * // Creates the provider object.
@@ -577,6 +579,8 @@ declare namespace firebase {
      *     console.</dd>
      * </dl>
      *
+     * @webonly
+     *
      * @example
      * ```javascript
      * // Creates the provider object.
@@ -625,6 +629,8 @@ declare namespace firebase {
      *     console.</dd>
      * </dl>
      *
+     * @webonly
+     *
      * @param provider The provider to authenticate.
      *     The provider has to be an OAuth provider. Non-OAuth providers like {@link
      *     firebase.auth.EmailAuthProvider} will throw an error.
@@ -992,6 +998,8 @@ declare namespace firebase {
    * generating notifications if the push message payload has a `notification`
    * parameter.
    *
+   * @webonly
+   *
    * @example
    * ```javascript
    * // Get the Messaging service for the default app
@@ -1020,6 +1028,8 @@ declare namespace firebase {
    * {@link firebase.storage.Storage `Storage`} service associated with a
    * specific app.
    *
+   * @webonly
+   *
    * @example
    * ```javascript
    * // Get the Storage service for the default app
@@ -1039,6 +1049,9 @@ declare namespace firebase {
 
   function firestore(app?: firebase.app.App): firebase.firestore.Firestore;
 
+  /**
+   * @webonly
+   */
   function functions(app?: firebase.app.App): firebase.functions.Functions;
 }
 
@@ -1095,6 +1108,8 @@ declare namespace firebase.app {
      * Gets the {@link firebase.messaging.Messaging `Messaging`} service for the
      * current app.
      *
+     * @webonly
+     *
      * @example
      * ```javascript
      * var messaging = app.messaging();
@@ -1139,6 +1154,8 @@ declare namespace firebase.app {
      * Gets the {@link firebase.storage.Storage `Storage`} service for the current
      * app, optionally initialized with a custom storage bucket.
      *
+     * @webonly
+     *
      * @example
      * ```javascript
      * var storage = app.storage();
@@ -1156,10 +1173,16 @@ declare namespace firebase.app {
      */
     storage(url?: string): firebase.storage.Storage;
     firestore(): firebase.firestore.Firestore;
+    /**
+     * @webonly
+     */
     functions(region?: string): firebase.functions.Functions;
   }
 }
 
+/**
+ * @webonly
+ */
 declare namespace firebase.functions {
   /**
    * An HttpsCallableResult wraps a single result from a function call.
@@ -1702,6 +1725,8 @@ declare namespace firebase.auth {
      *     Firebase console.</dd>
      * </dl>
      *
+     * @webonly
+     *
      * @example
      * ```javascript
      * // First, we perform the signInWithRedirect.
@@ -2508,6 +2533,8 @@ declare namespace firebase.auth {
      *     console.</dd>
      * </dl>
      *
+     * @webonly
+     *
      * @example
      * ```javascript
      * // Creates the provider object.
@@ -2569,6 +2596,8 @@ declare namespace firebase.auth {
      *     console.</dd>
      * </dl>
      *
+     * @webonly
+     *
      * @param provider The provider to authenticate.
      *     The provider has to be an OAuth provider. Non-OAuth providers like {@link
      *     firebase.auth.EmailAuthProvider} will throw an error.
@@ -3359,6 +3388,9 @@ declare namespace firebase.auth {
   /**
    * An {@link https://www.google.com/recaptcha/ reCAPTCHA}-based application
    * verifier.
+   *
+   * @webonly
+   *
    * @param container The reCAPTCHA container parameter. This
    *     has different meaning depending on whether the reCAPTCHA is hidden or
    *     visible. For a visible reCAPTCHA the container must be empty. If a string
@@ -3376,6 +3408,7 @@ declare namespace firebase.auth {
    */
   class RecaptchaVerifier extends RecaptchaVerifier_Instance {}
   /**
+   * @webonly
    * @hidden
    */
   class RecaptchaVerifier_Instance
@@ -5166,6 +5199,9 @@ declare namespace firebase.database.ServerValue {
   var TIMESTAMP: Object;
 }
 
+/**
+ * @webonly
+ */
 declare namespace firebase.messaging {
   /**
    * The Firebase Messaging service interface.
@@ -5270,6 +5306,9 @@ declare namespace firebase.messaging {
   function isSupported(): boolean;
 }
 
+/**
+ * @webonly
+ */
 declare namespace firebase.storage {
   /**
    * The full set of object metadata, including read-only properties.

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

@@ -50,8 +50,6 @@ toc:
     path: /docs/reference/node/firebase.auth.PhoneAuthProvider
   - title: "SAMLAuthProvider"
     path: /docs/reference/node/firebase.auth.SAMLAuthProvider
-  - title: "RecaptchaVerifier"
-    path: /docs/reference/node/firebase.auth.RecaptchaVerifier
   - title: "UserMetadata"
     path: /docs/reference/node/firebase.auth.UserMetadata
   - title: "User"

scripts/docgen/generate-docs.js

@@ -20,6 +20,7 @@ const yargs = require('yargs');
 const fs = require('mz/fs');
 const path = require('path');
 const yaml = require('js-yaml');
+const typescript = require('typescript');
 
 const repoPath = path.resolve(`${__dirname}/../..`);
 
@@ -41,6 +42,7 @@ const { api: apiType, source: sourceFile } = yargs
 const docPath = path.resolve(`${__dirname}/html/${apiType}`);
 const contentPath = path.resolve(`${__dirname}/content-sources/${apiType}`);
 const tempHomePath = path.resolve(`${contentPath}/HOME_TEMP.md`);
+const tempNodeSourcePath = path.resolve(`${__dirname}/index.node.d.ts`);
 const devsitePath = `/docs/reference/${apiType}/`;
 
 /**
@@ -58,7 +60,8 @@ function stripPath(path) {
  * Additional config options come from ./typedoc.js
  */
 function runTypedoc() {
-  const command = `${repoPath}/node_modules/.bin/typedoc ${sourceFile} \
+  const typeSource = apiType === 'node' ? tempNodeSourcePath : sourceFile;
+  const command = `${repoPath}/node_modules/.bin/typedoc ${typeSource} \
   --out ${docPath} \
   --readme ${tempHomePath} \
   --options ${__dirname}/typedoc.js \
@@ -111,7 +114,7 @@ function generateTempHomeMdFile(tocRaw, homeRaw) {
   const { toc } = yaml.safeLoad(tocRaw);
   let tocPageLines = [homeRaw, '# API Reference'];
   toc.forEach(group => {
-    tocPageLines.push(`\n## [${group.title}](${stripPath(group.path)})`);
+    tocPageLines.push(`\n## [${group.title}](${stripPath(group.path)}.html)`);
     group.section.forEach(item => {
       tocPageLines.push(`- [${item.title}](${stripPath(item.path)}.html)`);
     });
@@ -240,6 +243,55 @@ function fixAllLinks(htmlFiles) {
   return Promise.all(writePromises);
 }
 
+/**
+ * Generate an temporary abridged version of index.d.ts used to create
+ * Node docs.
+ */
+async function generateNodeSource() {
+  const sourceText = await fs.readFile(sourceFile, 'utf8');
+
+  // Parse index.d.ts. A dummy filename is required but it doesn't create a
+  // file.
+  let typescriptSourceFile = typescript.createSourceFile(
+    'temp.d.ts',
+    sourceText,
+    typescript.ScriptTarget.ES2015,
+    /*setParentNodes */ false
+  );
+
+  /**
+   * Typescript transformer function. Removes nodes tagged with @webonly.
+   */
+  const removeWebOnlyNodes = context => rootNode => {
+    function visit(node) {
+      if (
+        node.jsDoc &&
+        node.jsDoc.some(
+          item =>
+            item.tags &&
+            item.tags.some(tag => tag.tagName.escapedText === 'webonly')
+        )
+      ) {
+        return null;
+      }
+      return typescript.visitEachChild(node, visit, context);
+    }
+    return typescript.visitNode(rootNode, visit);
+  };
+
+  // Use above transformer on source AST to remove nodes tagged with @webonly.
+  const result = typescript.transform(typescriptSourceFile, [
+    removeWebOnlyNodes
+  ]);
+
+  // Convert transformed AST to text and write to file.
+  const printer = typescript.createPrinter();
+  return fs.writeFile(
+    tempNodeSourcePath,
+    printer.printFile(result.transformed[0])
+  );
+}
+
 /**
  * Main document generation process.
  *
@@ -262,13 +314,22 @@ Promise.all([
     tocText = tocRaw;
     return generateTempHomeMdFile(tocRaw, homeRaw);
   })
+  .then(() => {
+    if (apiType === 'node') {
+      return generateNodeSource();
+    }
+  })
   // Run main Typedoc process (uses index.d.ts and generated temp file above).
   .then(runTypedoc)
-  .then(output => {
+  .then(async output => {
     // Typedoc output.
     console.log(output.stdout);
     // Clean up temp home markdown file. (Nothing needs to wait for this.)
     fs.unlink(tempHomePath);
+    // Clean up temp node index.d.ts file if it exists.
+    if (await fs.exists(tempNodeSourcePath)) {
+      fs.unlink(tempNodeSourcePath);
+    }
     // Devsite doesn't like css.map files.
     return fs.unlink(`${docPath}/assets/css/main.css.map`);
   })

scripts/docgen/theme/assets/css/firebase.css

@@ -37,4 +37,17 @@
 
 .firebase-docs .tsd-breadcrumb .model-name {
     color: #333;
+}
+
+.firebase-docs .tsd-signature {
+    border-bottom: 1px solid #eee;
+}
+
+.firebase-docs .tsd-description {
+    display: block;
+    padding-left: 20px;
+}
+
+.firebase-docs li.tsd-description:not(:last-child) {
+    margin-bottom: 20px;
 }

scripts/docgen/theme/assets/css/main.css

@@ -486,11 +486,11 @@ footer .tsd-legend { display: inline-block; width: 25%; padding: 0; font-size: 1
 .tsd-signature-type { font-style: italic; font-weight: normal; }
 
 .tsd-signatures { padding: 0; margin: 0 0 1em 0; border: 1px solid #eee; }
-.tsd-signatures .tsd-signature { margin: 0; border-width: 1px 0 0 0; transition: background-color 0.1s; }
+.tsd-signatures .tsd-signature { margin: 0; border-width: 1px 0; transition: background-color 0.1s; }
 .tsd-signatures .tsd-signature:first-child { border-top-width: 0; }
 .tsd-signatures .tsd-signature.current { background-color: #eee; }
 .tsd-signatures.active > .tsd-signature { cursor: pointer; }
-.tsd-panel > .tsd-signatures { margin-left: -20px; margin-right: -20px; border-width: 1px 0; }
+.tsd-panel > .tsd-signatures { margin-left: -20px; margin-right: -20px; border-width: 1px 0; padding-bottom: 5px }
 .tsd-panel > .tsd-signatures .tsd-signature.tsd-kind-icon { padding-left: 40px; }
 .tsd-panel > a.anchor + .tsd-signatures { border-top-width: 0; margin-top: -20px; }
 

scripts/docgen/theme/partials/comment.hbs

@@ -12,8 +12,11 @@
             {{#if tags}}
                 <dl class="tsd-comment-tags">
                     {{#each tags}}
+                        {{#ifCond tagName '==' "webonly"}}
+                        {{else}}
                         <dt class="tag-{{tagName}}">{{tagName}}</dt>
                         <dd class="tag-body-{{tagName}}">{{#markdown}}{{{text}}}{{/markdown}}</dd>
+                        {{/ifCond}}
                     {{/each}}
                 </dl>
             {{/if}}

scripts/docgen/theme/partials/member.signatures.hbs

@@ -0,0 +1,8 @@
+<ul class="tsd-signatures {{cssClasses}}">
+    {{#each signatures}}
+        <li class="tsd-signature tsd-kind-icon">{{> member.signature.title }}</li>
+        <li class="tsd-description">
+            {{> member.signature.body }}
+        </li>
+    {{/each}}
+</ul>