build: check broken links in generated docs

.cloud-repo-tools.json

@@ -2,21 +2,21 @@
   "requiresKeyFile": true,
   "requiresProjectId": true,
   "product": "pubsub",
-  "client_reference_url": "https://googlecloudplatform.github.io/google-cloud-node/#/docs/pubsub/latest/pubsub",
+  "client_reference_url": "https://cloud.google.com/nodejs/docs/reference/pubsub/latest",
   "release_quality": "beta",
   "samples": [
     {
       "id": "subscriptions",
       "name": "Subscriptions",
       "file": "subscriptions.js",
-      "docs_link": "https://googlecloudplatform.github.io/google-cloud-node/#/docs/pubsub/latest/pubsub/subscription",
+      "docs_link": "https://cloud.google.com/nodejs/docs/reference/pubsub/latest/Subscription",
       "usage": "node subscriptions.js --help"
     },
     {
       "id": "topics",
       "name": "Topics",
       "file": "topics.js",
-      "docs_link": "https://googlecloudplatform.github.io/google-cloud-node/#/docs/pubsub/latest/pubsub/topic",
+      "docs_link": "https://cloud.google.com/nodejs/docs/reference/pubsub/latest/Topic",
       "usage": "node topics.js --help"
     }
   ]

.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

README.md

@@ -38,27 +38,17 @@
 // Imports the Google Cloud client library
 const {PubSub} = require('@google-cloud/pubsub');
 
-// Your Google Cloud Platform project ID
-const projectId = 'YOUR_PROJECT_ID';
-
-// Instantiates a client
-const pubsubClient = new PubSub({
-  projectId: projectId,
-});
-
-// The name for the new topic
-const topicName = 'my-new-topic';
-
-// Creates the new topic
-pubsubClient
-  .createTopic(topicName)
-  .then(results => {
-    const topic = results[0];
-    console.log(`Topic ${topic.name} created.`);
-  })
-  .catch(err => {
-    console.error('ERROR:', err);
-  });
+async function quickstart(
+  projectId = 'your-project-id', // Your Google Cloud Platform project ID
+  topicName = 'my-topic' // Name for the new topic to create
+) {
+  // Instantiates a client
+  const pubsub = new PubSub({projectId});
+
+  // Creates the new topic
+  const [topic] = await pubsub.createTopic(topicName);
+  console.log(`Topic ${topic.name} created.`);
+}
 ```
 
 ## Samples
@@ -108,11 +98,10 @@ Google APIs Client Libraries, in [Client Libraries Explained][explained].
 
 [explained]: https://cloud.google.com/apis/docs/client-libraries-explained
 
-[client-docs]: https://googlecloudplatform.github.io/google-cloud-node/#/docs/pubsub/latest/pubsub
+[client-docs]: https://cloud.google.com/nodejs/docs/reference/pubsub/latest
 [product-docs]: https://cloud.google.com/pubsub/docs
 [shell_img]: https://gstatic.com/cloudssh/images/open-btn.png
 [projects]: https://console.cloud.google.com/project
 [billing]: https://support.google.com/cloud/answer/6293499#enable-billing
 [enable_api]: https://console.cloud.google.com/flows/enableapi?apiid=pubsub.googleapis.com
 [auth]: https://cloud.google.com/docs/authentication/getting-started
-

package.json

@@ -36,6 +36,7 @@
     "samples-test": "cd samples/ && npm link ../ && npm test && cd ../",
     "test": "nyc mocha build/test",
     "lint": "eslint '**/*.js' && gts check",
+    "predocs": "npm run compile",
     "docs": "jsdoc -c .jsdoc.js",
     "fix": "eslint --fix '**/*.js' && gts fix",
     "generate-scaffolding": "repo-tools generate all && repo-tools generate lib_samples_readme -l samples/ --config ../.cloud-repo-tools.json",
@@ -82,7 +83,7 @@
     "eslint-plugin-node": "^8.0.0",
     "eslint-plugin-prettier": "^3.0.0",
     "gts": "^0.9.0",
-    "ink-docstrap": "^1.3.2",
+    "jsdoc-baseline": "git+https://github.com/hegemonic/jsdoc-baseline.git",
     "intelli-espower-loader": "^1.0.1",
     "jsdoc": "^3.5.5",
     "mocha": "^5.0.0",

src/iam.ts

@@ -142,8 +142,7 @@ export interface Policy {
  * SLA or deprecation policy, and may be subject to backward-incompatible
  * changes.*
  *
- * @constructor Iam
- * @mixin
+ * @class
  * @param {PubSub} pubsub PubSub Object.
  * @param {string} id The name of the topic or subscription.
  *
@@ -241,7 +240,7 @@ export class IAM {
    *
    * @throws {Error} If no policy is provided.
    *
-   * @param {object} policy The [policy](https://cloud.google.com/pubsub/docs/reference/rest/Shared.Types/Policy).
+   * @param {object} policy The [policy](https://cloud.google.com/pubsub/docs/reference/rest/v1/Policy).
    * @param {array} [policy.bindings] Bindings associate members with roles.
    * @param {Array<object>} [policy.rules] Rules to be applied to the policy.
    * @param {string} [policy.etag] Etags are used to perform a read-modify-write.

src/index.ts

@@ -14,6 +14,13 @@
  * limitations under the License.
  */
 
+/**
+ * @namespace google.pubsub.v1
+ */
+/**
+ * @namespace google.protobuf
+ */
+
 import {paginator} from '@google-cloud/paginator';
 import {replaceProjectIdToken} from '@google-cloud/projectify';
 import {promisifyAll} from '@google-cloud/promisify';
@@ -35,7 +42,8 @@ const opts = {} as gax.GrpcClientOptions;
 const {grpc} = new gax.GrpcClient(opts);
 
 /**
- * @type {string} - Project ID placeholder.
+ * Project ID placeholder.
+ * @type {string}
  * @private
  */
 const PROJECT_ID_PLACEHOLDER = '{{projectId}}';

src/lease-manager.ts

@@ -76,12 +76,14 @@ export class LeaseManager extends EventEmitter {
   }
   /**
    * @type {number}
+   * @private
    */
   get pending(): number {
     return this._pending.length;
   }
   /**
    * @type {number}
+   * @private
    */
   get size(): number {
     return this._messages.size;
@@ -91,6 +93,7 @@ export class LeaseManager extends EventEmitter {
    * isn't already running.
    *
    * @param {Message} message The message.
+   * @private
    */
   add(message: Message): void {
     const {allowExcessMessages} = this._options;
@@ -116,6 +119,7 @@ export class LeaseManager extends EventEmitter {
   }
   /**
    * Removes ALL messages from inventory.
+   * @private
    */
   clear(): void {
     const wasFull = this.isFull();
@@ -134,6 +138,7 @@ export class LeaseManager extends EventEmitter {
    * Indicates if we're at or over capacity.
    *
    * @returns {boolean}
+   * @private
    */
   isFull(): boolean {
     const {maxBytes, maxMessages} = this._options;
@@ -146,6 +151,7 @@ export class LeaseManager extends EventEmitter {
    * @fires LeaseManager#free
    *
    * @param {Message} message The message to remove.
+   * @private
    */
   remove(message: Message): void {
     if (!this._messages.has(message)) {
@@ -174,6 +180,7 @@ export class LeaseManager extends EventEmitter {
    * Sets options for the LeaseManager.
    *
    * @param {FlowControlOptions} [options] The options.
+   * @private
    */
   setOptions(options: FlowControlOptions): void {
     const defaults: FlowControlOptions = {

src/message-queues.ts

@@ -65,6 +65,7 @@ export abstract class MessageQueue {
    * Gets the default buffer time in ms.
    *
    * @returns {number}
+   * @private
    */
   get maxMilliseconds(): number {
     return this._options!.maxMilliseconds!;
@@ -74,6 +75,7 @@ export abstract class MessageQueue {
    *
    * @param {Message} message The message to add.
    * @param {number} [deadline] The deadline.
+   * @private
    */
   add({ackId}: Message, deadline?: number): void {
     const {maxMessages, maxMilliseconds} = this._options;
@@ -89,6 +91,7 @@ export abstract class MessageQueue {
   }
   /**
    * Sends a batch of messages.
+   * @private
    */
   async flush(): Promise<void> {
     if (this._timer) {
@@ -118,6 +121,7 @@ export abstract class MessageQueue {
    * Returns a promise that resolves after the next flush occurs.
    *
    * @returns {Promise}
+   * @private
    */
   onFlush(): Promise<void> {
     if (!this._onFlush) {
@@ -129,6 +133,7 @@ export abstract class MessageQueue {
    * Set the batching options.
    *
    * @param {BatchOptions} options Batching options.
+   * @private
    */
   setOptions(options): void {
     const defaults: BatchOptions = {maxMessages: 3000, maxMilliseconds: 100};

src/message-stream.ts

@@ -156,6 +156,7 @@ export class MessageStream extends PassThrough {
    * Destroys the stream and any underlying streams.
    *
    * @param {error?} err An error to emit, if any.
+   * @private
    */
   destroy(err?: Error): void {
     if (this.destroyed) {

src/publisher.ts

@@ -76,7 +76,7 @@ export class Publisher {
      * The topic of this publisher.
      *
      * @name Publisher#topic
-     * @type {Topic} topic
+     * @type {Topic}
      */
     this.topic = topic;
     // this object keeps track of all messages scheduled to be published

src/subscriber.ts

@@ -81,12 +81,14 @@ export class Message {
    * The length of the message data.
    *
    * @type {number}
+   * @private
    */
   get length() {
     return this._length;
   }
   /**
    * Acknowledges the message.
+   * @private
    */
   ack(): void {
     if (!this._handled) {
@@ -98,6 +100,7 @@ export class Message {
    * Modifies the ack deadline.
    *
    * @param {number} deadline The number of seconds to extend the deadline.
+   * @private
    */
   modAck(deadline: number): void {
     if (!this._handled) {
@@ -110,6 +113,7 @@ export class Message {
    *
    * @param {number} [delay=0] The desired time to wait before the
    *     redelivery occurs.
+   * @private
    */
   nack(delay?: number): void {
     if (!this._handled) {
@@ -186,6 +190,7 @@ export class Subscriber extends EventEmitter {
    * The 99th percentile of request latencies.
    *
    * @type {number}
+   * @private
    */
   get modAckLatency() {
     const latency = this._latencies.percentile(99);
@@ -201,6 +206,7 @@ export class Subscriber extends EventEmitter {
    * The full name of the Subscription.
    *
    * @type {string}
+   * @private
    */
   get name(): string {
     if (!this._name) {
@@ -215,6 +221,7 @@ export class Subscriber extends EventEmitter {
    *
    * @param {Message} message The message to acknowledge.
    * @returns {Promise}
+   * @private
    */
   async ack(message: Message): Promise<void> {
     if (!this._isUserSetDeadline) {
@@ -232,6 +239,7 @@ export class Subscriber extends EventEmitter {
    * acks/modAcks are finished.
    *
    * @returns {Promise}
+   * @private
    */
   async close(): Promise<void> {
     if (!this.isOpen) {
@@ -248,6 +256,7 @@ export class Subscriber extends EventEmitter {
    * Gets the subscriber client instance.
    *
    * @returns {Promise<object>}
+   * @private
    */
   async getClient(): Promise<ClientStub> {
     const pubsub = this._subscription.pubsub;
@@ -263,6 +272,7 @@ export class Subscriber extends EventEmitter {
    * @param {Message} message The message to modify.
    * @param {number} deadline The deadline.
    * @returns {Promise}
+   * @private
    */
   async modAck(message: Message, deadline: number): Promise<void> {
     const startTime = Date.now();
@@ -280,13 +290,15 @@ export class Subscriber extends EventEmitter {
    * @param {Message} message The message.
    * @param {number} [delay=0] Delay to wait before redelivery.
    * @return {Promise}
+   * @private
    */
   async nack(message: Message, delay = 0): Promise<void> {
     await this.modAck(message, delay);
     this._inventory.remove(message);
   }
   /**
    * Starts pulling messages.
+   * @private
    */
   open(): void {
     const {batching, flowControl, streamingOptions} = this._options;
@@ -308,6 +320,7 @@ export class Subscriber extends EventEmitter {
    * Sets subscriber options.
    *
    * @param {SubscriberOptions} options The options.
+   * @private
    */
   setOptions(options: SubscriberOptions): void {
     this._options = options;

src/v1/doc/google/protobuf/doc_timestamp.js

@@ -87,13 +87,11 @@
  * 01:30 UTC on January 15, 2017.
  *
  * 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]
+ * standard [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.
+ * can use 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