build: check broken links in generated docs (#511)

* build: check dead links on Kokoro

* recursive crawl local links

* add @Private jsdoc tag to methods of private classes

* fix dead links in timestamp

* npm run fix

* stop running lint post test

.jsdoc.js

@@ -20,7 +20,7 @@ module.exports = {
   opts: {
     readme: './README.md',
     package: './package.json',
-    template: './node_modules/ink-docstrap/template',
+    template: './node_modules/jsdoc-baseline',
     recurse: true,
     verbose: true,
     destination: './docs/'

.kokoro/docs.sh

@@ -23,3 +23,11 @@ cd $(dirname $0)/..
 npm install
 
 npm run docs
+
+# Check broken links
+BIN=./node_modules/.bin
+
+npm install broken-link-checker
+npm install http-server
+$BIN/http-server -p 8080 docs/ &
+$BIN/blc -r http://localhost:8080

dev/src/backoff.ts

@@ -104,30 +104,40 @@ export class ExponentialBackoff {
    * The initial delay (used as the base delay on the first retry attempt).
    * Note that jitter will still be applied, so the actual delay could be as
    * little as 0.5*initialDelayMs (based on a jitter factor of 1.0).
+   *
+   * @private
    */
   private readonly initialDelayMs: number;
 
   /**
    * The multiplier to use to determine the extended base delay after each
    * attempt.
+   *
+   * @private
    */
   private readonly backoffFactor: number;
 
   /**
    * The maximum base delay after which no further backoff is performed.
    * Note that jitter will still be applied, so the actual delay could be as
    * much as 1.5*maxDelayMs (based on a jitter factor of 1.0).
+   *
+   * @private
    */
   private readonly maxDelayMs: number;
 
   /**
    * The jitter factor that controls the random distribution of the backoff
    * points.
+   *
+   * @private
    */
   private readonly jitterFactor: number;
 
   /**
    * The backoff delay of the current attempt.
+   *
+   * @private
    */
   private currentBaseMs = 0;
 
@@ -152,6 +162,8 @@ export class ExponentialBackoff {
    * The very next backoffAndWait() will have no delay. If it is called again
    * (i.e. due to an error), initialDelayMs (plus jitter) will be used, and
    * subsequent ones will increase according to the backoffFactor.
+   *
+   * @private
    */
   reset(): void {
     this.currentBaseMs = 0;
@@ -160,6 +172,8 @@ export class ExponentialBackoff {
   /**
    * Resets the backoff delay to the maximum delay (e.g. for use after a
    * RESOURCE_EXHAUSTED error).
+   *
+   * @private
    */
   resetToMax(): void {
     this.currentBaseMs = this.maxDelayMs;
@@ -170,6 +184,7 @@ export class ExponentialBackoff {
    * delay for any subsequent attempts.
    *
    * @return A Promise that resolves when the current delay elapsed.
+   * @private
    */
   backoffAndWait(): Promise<void> {
     // First schedule using the current base (which may be 0 and should be
@@ -197,8 +212,8 @@ export class ExponentialBackoff {
    * Returns a randomized "jitter" delay based on the current base and jitter
    * factor.
    *
-   * @private
    * @returns {number} The jitter to apply based on the current delay.
+   * @private
    */
   private jitterDelayMs() {
     return (Math.random() - 0.5) * this.jitterFactor * this.currentBaseMs;

dev/src/document.ts

@@ -919,7 +919,10 @@ export class DocumentTransform {
     return Array.from(this._transforms.keys());
   }
 
-  /** Validates the user provided field values in this document transform. */
+  /**
+   * Validates the user provided field values in this document transform.
+   * @private
+   */
   validate(): void {
     this._transforms.forEach(transform => transform.validate(this._validator));
   }

dev/src/field-value.ts

@@ -193,6 +193,7 @@ export abstract class FieldTransform extends FieldValue {
 export class DeleteTransform extends FieldTransform {
   /**
    * Sentinel value for a field delete.
+   * @private
    */
   static DELETE_SENTINEL = new DeleteTransform();
 
@@ -202,13 +203,15 @@ export class DeleteTransform extends FieldTransform {
 
   /**
    * Deletes are included in document masks.
+   * @private
    */
   get includeInDocumentMask(): true {
     return true;
   }
 
   /**
    * Deletes are are omitted from document transforms.
+   * @private
    */
   get includeInDocumentTransform(): false {
     return false;
@@ -292,13 +295,15 @@ class ArrayUnionTransform extends FieldTransform {
 
   /**
    * Array transforms are omitted from document masks.
+   * @private
    */
   get includeInDocumentMask(): false {
     return false;
   }
 
   /**
    * Array transforms are included in document transforms.
+   * @private
    */
   get includeInDocumentTransform(): true {
     return true;
@@ -346,13 +351,15 @@ class ArrayRemoveTransform extends FieldTransform {
 
   /**
    * Array transforms are omitted from document masks.
+   * @private
    */
   get includeInDocumentMask(): false {
     return false;
   }
 
   /**
    * Array transforms are included in document transforms.
+   * @private
    */
   get includeInDocumentTransform(): true {
     return true;

dev/src/pool.ts

@@ -27,7 +27,10 @@ import * as assert from 'assert';
  * @private
  */
 export class ClientPool<T> {
-  /** Stores each active clients and how many operations it has outstanding. */
+  /**
+   * Stores each active clients and how many operations it has outstanding.
+   * @private
+   */
   private activeClients: Map<T, number> = new Map();
 
   /**
@@ -43,6 +46,8 @@ export class ClientPool<T> {
   /**
    * Returns an already existing client if it has less than the maximum number
    * of concurrent operations or initializes and returns a new client.
+   *
+   * @private
    */
   private acquire(): T {
     let selectedClient: T|null = null;
@@ -70,6 +75,7 @@ export class ClientPool<T> {
   /**
    * Reduces the number of operations for the provided client, potentially
    * removing it from the pool of active clients.
+   * @private
    */
   private release(client: T): void {
     let requestCount = this.activeClients.get(client) || 0;
@@ -87,6 +93,7 @@ export class ClientPool<T> {
    * The number of currently registered clients.
    *
    * @return Number of currently registered clients.
+   * @private
    */
   // Visible for testing.
   get size(): number {
@@ -101,6 +108,7 @@ export class ClientPool<T> {
    * @param op A callback function that returns a Promise. The client T will
    * be returned to the pool when callback finishes.
    * @return A Promise that resolves with the result of `op`.
+   * @private
    */
   run<V>(op: (client: T) => Promise<V>): Promise<V> {
     const client = this.acquire();
@@ -119,6 +127,8 @@ export class ClientPool<T> {
   /**
    * Deletes clients that are no longer executing operations. Keeps up to one
    * idle client to reduce future initialization costs.
+   *
+   * @private
    */
   private garbageCollect(): void {
     let idleClients = 0;

dev/src/reference.ts

@@ -518,6 +518,7 @@ class FieldOrder {
 
   /**
    * Generates the proto representation for this field order.
+   * @private
    */
   toProto(): api.StructuredQuery.IOrder {
     return {

dev/src/v1beta1/doc/google/protobuf/doc_timestamp.js

@@ -89,14 +89,14 @@
  *
  * In JavaScript, one can convert a Date object to this format using the
  * standard
- * [toISOString()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString]
+ * [toISOString()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString)
  * method. In Python, a standard `datetime.datetime` object can be converted
  * to this format using
  * [`strftime`](https://docs.python.org/2/library/time.html#time.strftime) with
  * the time format spec '%Y-%m-%dT%H:%M:%S.%fZ'. Likewise, in Java, one can use
- * the Joda Time's [`ISODateTimeFormat.dateTime()`](https://cloud.google.com
- * http://www.joda.org/joda-time/apidocs/org/joda/time/format/ISODateTimeFormat.html#dateTime--
- * ) to obtain a formatter capable of generating timestamps in this format.
+ * the Joda Time's
+ * [`ISODateTimeFormat.dateTime()`](https://www.joda.org/joda-time/apidocs/org/joda/time/format/ISODateTimeFormat.html#dateTime--)
+ * to obtain a formatter capable of generating timestamps in this format.
  *
  * @property {number} seconds
  *   Represents seconds of UTC time since Unix epoch

dev/src/validate.ts

@@ -129,6 +129,7 @@ export class Validator {
    * @param {number} minSize The minimum number of elements to enforce.
    * @throws if the expectation is not met.
    * @returns {boolean} 'true' when the minimum number of elements is available.
+   * @private
    */
   minNumberOfArguments(funcName, args, minSize): boolean {
     if (args.length < minSize) {
@@ -149,6 +150,7 @@ export class Validator {
    * @throws if the expectation is not met.
    * @returns {boolean} 'true' when only the maximum number of elements is
    * specified.
+   * @private
    */
   maxNumberOfArguments(funcName, args, maxSize): boolean {
     if (args.length > maxSize) {

dev/src/watch.ts

@@ -533,6 +533,7 @@ export class Watch {
      * Applies the mutations in changeMap to both the document tree and the
      * document lookup map. Modified docMap in-place and returns the updated
      * state.
+     * @private
      */
     const computeSnapshot =
         (docTree: rbtree, docMap: Map<string, QueryDocumentSnapshot>,
@@ -548,6 +549,7 @@ export class Watch {
           /**
            * Applies a document delete to the document tree and the document
            * map. Returns the corresponding DocumentChange event.
+           * @private
            */
           function deleteDoc(name: string): DocumentChange {
             assert(updatedMap.has(name), 'Document to delete does not exist');
@@ -563,6 +565,7 @@ export class Watch {
           /**
            * Applies a document add to the document tree and the document map.
            * Returns the corresponding DocumentChange event.
+           * @private
            */
           function addDoc(newDocument: QueryDocumentSnapshot): DocumentChange {
             const name = newDocument.ref.formattedName;
@@ -578,6 +581,7 @@ export class Watch {
            * Applies a document modification to the document tree and the
            * document map. Returns the DocumentChange event for successful
            * modifications.
+           * @private
            */
           function modifyDoc(newDocument: QueryDocumentSnapshot):
               DocumentChange|null {

package.json

@@ -42,8 +42,7 @@
     "compile": "tsc -p . && cp -r dev/protos build && cp -r dev/test/fake-certificate.json build/test/fake-certificate.json  && cp dev/src/v1beta1/firestore_client_config.json build/src/v1beta1/ && cp dev/conformance/test-definition.proto build/conformance && cp dev/conformance/test-suite.binproto build/conformance",
     "fix": "gts fix",
     "prepare": "npm run compile",
-    "pretest-only": "npm run compile",
-    "posttest": "npm run lint"
+    "pretest-only": "npm run compile"
   },
   "dependencies": {
     "@google-cloud/projectify": "^0.3.0",
@@ -74,7 +73,7 @@
     "duplexify": "^3.6.0",
     "gts": "^0.9.0",
     "hard-rejection": "^1.0.0",
-    "ink-docstrap": "git+https://github.com/docstrap/docstrap.git",
+    "jsdoc-baseline": "git+https://github.com/hegemonic/jsdoc-baseline.git",
     "intelli-espower-loader": "^1.0.1",
     "jsdoc": "^3.5.5",
     "mocha": "^5.2.0",

synth.py

@@ -50,6 +50,16 @@
 
 s.copy(templates)
 
+# [START fix-dead-link]
+s.replace('**/doc/google/protobuf/doc_timestamp.js',
+        'https:\/\/cloud\.google\.com[\s\*]*http:\/\/(.*)[\s\*]*\)',
+        r"https://\1)")
+
+s.replace('**/doc/google/protobuf/doc_timestamp.js',
+        'toISOString\]',
+        'toISOString)')
+# [END fix-dead-link]
+
 # Node.js specific cleanup
 subprocess.run(["npm", "install"])
 subprocess.run(["npm", "run", "fix"])