fix(docs): fix formatting of the docs (#513)

linkinator.config.json

@@ -2,6 +2,7 @@
   "recurse": true,
   "skip": [
     "https://codecov.io/gh/googleapis/",
-    "www.googleapis.com"
+    "www.googleapis.com",
+    "http://goo.gl/f2SXcb"
   ]
 }

package.json

@@ -82,7 +82,7 @@
     "gts": "^1.0.0",
     "ink-docstrap": "^1.3.2",
     "intelli-espower-loader": "^1.0.1",
-    "jsdoc": "^3.6.2",
+    "jsdoc": "^3.6.3",
     "jsdoc-fresh": "^1.0.1",
     "linkinator": "^1.5.0",
     "mocha": "^6.1.4",

src/dataset.ts

@@ -322,8 +322,7 @@ class Dataset extends ServiceObject {
      *     // All models have been retrieved
      *   });
      *
-     * @example <caption>If you anticipate many results, you can end a stream
-     * early to prevent unnecessary processing and API requests.</caption>
+     * @example <caption>If you anticipate many results, you can end a stream early to prevent unnecessary processing and API requests.</caption>
      * dataset.getModelsStream()
      *   .on('data', function(model) {
      *     this.end();
@@ -602,8 +601,7 @@ class Dataset extends ServiceObject {
    *   // models is an array of `Model` objects.
    * });
    *
-   * @example <caption>To control how many API requests are made and page
-   * through the results manually, set `autoPaginate` to `false`.</caption>
+   * @example <caption>To control how many API requests are made and page through the results manually, set `autoPaginate` to `false`.</caption>
    * function manualPaginationCallback(err, models, nextQuery, apiResponse) {
    *   if (nextQuery) {
    *     // More results exist.
@@ -615,8 +613,7 @@ class Dataset extends ServiceObject {
    *   autoPaginate: false
    * }, manualPaginationCallback);
    *
-   * @example <caption>If the callback is omitted, we'll return a Promise.
-   * </caption>
+   * @example <caption>If the callback is omitted, we'll return a Promise.</caption>
    * dataset.getModels().then((data) => {
    *   const models = data[0];
    * });

src/index.ts

@@ -157,6 +157,17 @@ export interface BigQueryDatetimeOptions {
 
 export type QueryParameter = bigquery.IQueryParameter;
 
+export interface BigQueryOptions extends common.GoogleAuthOptions {
+  autoRetry?: boolean;
+  maxRetries?: number;
+  location?: string;
+  /**
+   * The API endpoint of the service used to make requests.
+   * Defaults to `www.googleapis.com`.
+   */
+  apiEndpoint?: string;
+}
+
 /**
  * @typedef {object} BigQueryOptions
  * @property {string} [projectId] The project ID from the Google Developer's
@@ -189,17 +200,8 @@ export type QueryParameter = bigquery.IQueryParameter;
  * @property {string[]} [scopes] Additional OAuth scopes to use in requests. For
  *     example, to access an external data source, you may need the
  *     `https://www.googleapis.com/auth/drive.readonly` scope.
+ * @property {string=} apiEndpoint The API endpoint of the service used to make requests. Defaults to `www.googleapis.com`.
  */
-export interface BigQueryOptions extends common.GoogleAuthOptions {
-  autoRetry?: boolean;
-  maxRetries?: number;
-  location?: string;
-  /**
-   * The API endpoint of the service used to make requests.
-   * Defaults to `www.googleapis.com`.
-   */
-  apiEndpoint?: string;
-}
 
 /**
  * In the following examples from this page and the other modules (`Dataset`,
@@ -215,21 +217,19 @@ export interface BigQueryOptions extends common.GoogleAuthOptions {
  *
  * @param {BigQueryOptions} options Constructor options.
  *
- * @example <caption>Install the client library with <a
- * href="https://www.npmjs.com/">npm</a>:</caption> npm install --save
- * @google-cloud/bigquery
+ * @example <caption>Install the client library with <a href="https://www.npmjs.com/">npm</a>:</caption>
+ * npm install @google-cloud/bigquery
  *
  * @example <caption>Import the client library</caption>
  * const {BigQuery} = require('@google-cloud/bigquery');
  *
- * @example <caption>Create a client that uses <a
- * href="https://cloud.google.com/docs/authentication/production#providing_credentials_to_your_application">Application
- * Default Credentials (ADC)</a>:</caption> const bigquery = new BigQuery();
+ * @example <caption>Create a client that uses <a href="https://cloud.google.com/docs/authentication/production#providing_credentials_to_your_application">Application Default Credentials (ADC)</a>:</caption>
+ * const bigquery = new BigQuery();
  *
- * @example <caption>Create a client with <a
- * href="https://cloud.google.com/docs/authentication/production#obtaining_and_providing_service_account_credentials_manually">explicit
- * credentials</a>:</caption> const bigquery = new BigQuery({ projectId:
- * 'your-project-id', keyFilename: '/path/to/keyfile.json'
+ * @example <caption>Create a client with <a href="https://cloud.google.com/docs/authentication/production#obtaining_and_providing_service_account_credentials_manually">explicit credentials</a>:</caption>
+ * const bigquery = new BigQuery({
+ *   projectId: 'your-project-id',
+ *   keyFilename: '/path/to/keyfile.json'
  * });
  *
  * @example <caption>include:samples/quickstart.js</caption>
@@ -1753,21 +1753,19 @@ export {Table};
  * @module {object} @google-cloud/bigquery
  * @alias nodejs-bigquery
  *
- * @example <caption>Install the client library with <a
- * href="https://www.npmjs.com/">npm</a>:</caption> npm install --save
- * @google-cloud/bigquery
+ * @example <caption>Install the client library with <a href="https://www.npmjs.com/">npm</a>:</caption>
+ * npm install @google-cloud/bigquery
  *
  * @example <caption>Import the client library</caption>
  * const {BigQuery} = require('@google-cloud/bigquery');
  *
- * @example <caption>Create a client that uses <a
- * href="https://cloud.google.com/docs/authentication/production#providing_credentials_to_your_application">Application
- * Default Credentials (ADC)</a>:</caption> const bigquery = new BigQuery();
+ * @example <caption>Create a client that uses <a href="https://cloud.google.com/docs/authentication/production#providing_credentials_to_your_application">Application Default Credentials (ADC)</a>:</caption>
+ * const bigquery = new BigQuery();
  *
- * @example <caption>Create a client with <a
- * href="https://cloud.google.com/docs/authentication/production#obtaining_and_providing_service_account_credentials_manually">explicit
- * credentials</a>:</caption> const bigquery = new BigQuery({ projectId:
- * 'your-project-id', keyFilename: '/path/to/keyfile.json'
+ * @example <caption>Create a client with <a href="https://cloud.google.com/docs/authentication/production#obtaining_and_providing_service_account_credentials_manually">explicit credentials</a>:</caption>
+ * const bigquery = new BigQuery({
+ *   projectId: 'your-project-id',
+ *   keyFilename: '/path/to/keyfile.json'
  * });
  *
  * @example <caption>include:samples/quickstart.js</caption>

src/model.ts

@@ -55,8 +55,7 @@ class Model extends common.ServiceObject {
        *
        * model.delete((err, apiResponse) => {});
        *
-       * @example <caption>If the callback is omitted we'll return a Promise.
-       * </caption>
+       * @example <caption>If the callback is omitted we'll return a Promise.</caption>
        * const [apiResponse] = await model.delete();
        */
       delete: true,
@@ -79,8 +78,7 @@ class Model extends common.ServiceObject {
        *
        * model.exists((err, exists) => {});
        *
-       * @example <caption>If the callback is omitted we'll return a Promise.
-       * </caption>
+       * @example <caption>If the callback is omitted we'll return a Promise.</caption>
        * const [exists] = await model.exists();
        */
       exists: true,
@@ -110,8 +108,7 @@ class Model extends common.ServiceObject {
        *   }
        * });
        *
-       * @example <caption>If the callback is omitted we'll return a Promise.
-       * </caption>
+       * @example <caption>If the callback is omitted we'll return a Promise.</caption>
        * await model.get();
        */
       get: true,
@@ -137,8 +134,7 @@ class Model extends common.ServiceObject {
        *
        * model.getMetadata((err, metadata, apiResponse) => {});
        *
-       * @example <caption>If the callback is omitted we'll return a Promise.
-       * </caption>
+       * @example <caption>If the callback is omitted we'll return a Promise.</caption>
        * const [metadata, apiResponse] = await model.getMetadata();
        */
       getMetadata: true,
@@ -167,8 +163,7 @@ class Model extends common.ServiceObject {
        *
        * model.setMetadata(metadata, (err, metadata, apiResponse) => {});
        *
-       * @example <caption>If the callback is omitted we'll return a Promise.
-       * </caption>
+       * @example <caption>If the callback is omitted we'll return a Promise.</caption>
        * const [metadata, apiResponse] = await model.setMetadata(metadata);
        */
       setMetadata: true,

src/table.ts

@@ -1786,9 +1786,7 @@ class Table extends common.ServiceObject {
    * table.insert(rows, insertHandler);
    *
    * //-
-   * // Insert a row as according to the <a
-   * href="https://cloud.google.com/bigquery/docs/reference/v2/tabledata/insertAll">
-   * // specification</a>.
+   * // Insert a row as according to the <a href="https://cloud.google.com/bigquery/docs/reference/v2/tabledata/insertAll">specification</a>.
    * //-
    * const row = {
    *   insertId: '1',
@@ -1806,9 +1804,7 @@ class Table extends common.ServiceObject {
    * table.insert(row, options, insertHandler);
    *
    * //-
-   * // Handling the response. See <a
-   * href="https://developers.google.com/bigquery/troubleshooting-errors">
-   * // Troubleshooting Errors</a> for best practices on how to handle errors.
+   * // Handling the response. See <a href="https://developers.google.com/bigquery/troubleshooting-errors">Troubleshooting Errors</a> for best practices on how to handle errors.
    * //-
    * function insertHandler(err, apiResponse) {
    *   if (err) {