docs: various jsdoc fixes

src/batch-transaction.js

@@ -140,7 +140,7 @@ class BatchTransaction extends Transaction {
    * @private
    *
    * @param {object} config The request config.
-   * @param {function} Callback function.
+   * @param {function} callback Callback function.
    */
   createPartitions_(config, callback) {
     const self = this;
@@ -218,7 +218,7 @@ class BatchTransaction extends Transaction {
    * @param {ReadPartition|QueryParition} partition The partition object.
    * @param {object} [partition.gaxOptions] Request configuration options,
    *     outlined here: https://googleapis.github.io/gax-nodejs/CallSettings.html.
-   * @param {TransactionRequestReadCallback|RunCallback} callback Callback
+   * @param {TransactionRequestReadCallback|RunCallback} [callback] Callback
    *     function.
    * @returns {Promise<RunResponse>|Promise<TransactionRequestReadResponse>}
    *

src/codec.js

@@ -88,6 +88,8 @@ codec.TYPE = TYPE;
  * struct characteristics.
  *
  * @private
+ *
+ * @returns {array}
  */
 function Struct() {
   const struct = [];
@@ -161,6 +163,9 @@ module.exports.Struct = Struct;
 /**
  * Wherever a row object is returned, it is assigned a "toJSON" function. This
  * function will create that function in a consistent format.
+ *
+ * @param {array} row The row to generate JSON for.
+ * @returns {function}
  */
 function generateToJSONFromRow(row) {
   return function(options) {
@@ -205,6 +210,10 @@ codec.generateToJSONFromRow = generateToJSONFromRow;
  * Re-decode after the generic gRPC decoding step.
  *
  * @private
+ *
+ * @param {*} value Value to decode
+ * @param {object[]} field Struct fields
+ * @returns {*}
  */
 function decode(value, field) {
   function decodeValue_(decoded, type) {
@@ -265,6 +274,9 @@ codec.decode = decode;
  * Encode a value in the format the API expects.
  *
  * @private
+ *
+ * @param {*} value The value to be encoded
+ * @returns {*}
  */
 function encode(value) {
   function preEncode(value) {
@@ -314,7 +326,7 @@ codec.encode = encode;
  * @private
  *
  * @param {*} field - The field value.
- * @return {string}
+ * @returns {string}
  *
  * @example
  * Database.getType_(NaN);

src/database.js

@@ -916,8 +916,8 @@ class Database extends ServiceObject {
    *
    * @private
    *
-   * @param {object} config
-   * @param {function} callback
+   * @param {object} config Request config
+   * @param {function} callback Callback function
    */
   makePooledRequest_(config, callback) {
     const self = this;
@@ -940,7 +940,7 @@ class Database extends ServiceObject {
    *
    * @private
    *
-   * @param {object} config
+   * @param {object} config Request config
    * @returns {Stream}
    */
   makePooledStreamingRequest_(config) {
@@ -1412,28 +1412,29 @@ class Database extends ServiceObject {
    * region_tag:spanner_read_write_transaction
    * Read-write transaction:
    */
-  runTransaction(options, runFn) {
+  runTransaction(options, callback) {
     if (is.fn(options)) {
-      runFn = options;
+      callback = options;
       options = null;
     }
     options = extend({}, options);
     this.getTransaction(options, function(err, transaction) {
       if (err) {
-        runFn(err);
+        callback(err);
         return;
       }
       transaction.beginTime_ = Date.now();
-      transaction.runFn_ = runFn;
+      transaction.runFn_ = callback;
       if (options && options.timeout) {
         transaction.timeout_ = options.timeout;
         delete options.timeout;
       }
-      runFn(null, transaction);
+      callback(null, transaction);
     });
   }
   /**
    * A function to execute in the context of a transaction.
+   * @callback RunTransactionAsyncCallback
    * @param {Transaction} transaction The transaction object. The transaction has
    *     already been created, and is ready to be queried and committed against.
    */
@@ -1464,6 +1465,9 @@ class Database extends ServiceObject {
    * @see [Transactions](https://cloud.google.com/spanner/docs/transactions)
    * @see [Timestamp Bounds](https://cloud.google.com/spanner/docs/timestamp-bounds)
    *
+   * @param {RunTransactionAsyncCallback} callback A function to execute in the
+   *      context of a transaction.
+   * @returns {Promise}
    *
    * @example
    * const {Spanner} = require('@google-cloud/spanner');
@@ -1482,12 +1486,12 @@ class Database extends ServiceObject {
    *   // ...
    * });
    */
-  runTransactionAsync(runFn) {
+  runTransactionAsync(callback) {
     return retry(() =>
       this.getTransaction()
         .then(r => {
           const transaction = r[0];
-          return runFn(transaction);
+          return callback(transaction);
         })
         .catch(e => {
           if (e.code === Transaction.ABORTED) throw e;
@@ -1635,6 +1639,7 @@ class Database extends ServiceObject {
    *
    * @param {string} instanceName The formatted instance name.
    * @param {string} name The table name.
+   * @returns {string}
    *
    * @example
    * Database.formatName_(

src/index.js

@@ -615,6 +615,9 @@ class Spanner extends Service {
    * {{projectId}} placeholders, if necessary.
    *
    * @private
+   *
+   * @param {object} config Request config
+   * @param {function} callback Callback function
    */
   prepareGapicRequest_(config, callback) {
     const self = this;
@@ -647,6 +650,7 @@ class Spanner extends Service {
    * @param {function} config.method The gax method to call.
    * @param {object} config.reqOpts Request options.
    * @param {function} [callback] Callback function.
+   * @returns {Promise}
    */
   request(config, callback) {
     const self = this;
@@ -680,6 +684,7 @@ class Spanner extends Service {
    * @param {function} config.method The gax method to call.
    * @param {object} config.reqOpts Request options.
    * @param {function} [callback] Callback function.
+   * @returns {Stream}
    */
   requestStream(config) {
     const self = this;

src/instance.js

@@ -588,7 +588,7 @@ class Instance extends common.ServiceObject {
    * @see {@link v1.InstanceAdminClient#updateInstance}
    * @see [UpdateInstance API Documentation](https://cloud.google.com/spanner/docs/reference/rpc/google.spanner.admin.instance.v1#google.spanner.admin.instance.v1.InstanceAdmin.UpdateInstance)
    *
-   * @param {object<string, *>} metadata The metadata you wish to set.
+   * @param {object} metadata The metadata you wish to set.
    * @param {LongRunningOperationCallback} [callback] Callback function.
    * @returns {Promise<LongRunningOperationResponse>}
    *
@@ -650,6 +650,7 @@ class Instance extends common.ServiceObject {
    *
    * @param {string} projectId The project ID.
    * @param {string} name The instance name.
+   * @returns {string}
    *
    * @example
    * Instance.formatName_('grape-spaceship-123', 'my-instance');

src/partial-result-stream.js

@@ -38,9 +38,10 @@ const RowBuilder = require('./row-builder');
  * @private
  *
  * @class
- * @param {function} requestFn - The function that makes an API request. It will
+ * @param {function} requestFn The function that makes an API request. It will
  *     receive one argument, `resumeToken`, which should be used however is
  *     necessary to send to the API for additional requests.
+ * @param {object} options Request options
  */
 function partialResultStream(requestFn, options) {
   let lastResumeToken;

src/row-builder.js

@@ -39,12 +39,16 @@ class RowBuilder {
   }
   /**
    * Add a PartialResultSet response object to the pending rows.
+   *
+   * @param {array} row Row values
    */
   addRow(row) {
     this.chunks = this.chunks.concat(row);
   }
   /**
    * Appends element to row.
+   *
+   * @param {*} value Row value
    */
   append(value) {
     if (this.currentRow.length === this.fields.length) {
@@ -81,6 +85,8 @@ class RowBuilder {
   }
   /**
    * Flush already complete rows.
+   *
+   * @returns {array}
    */
   flush() {
     const rowsToReturn = this.rows;
@@ -97,6 +103,9 @@ class RowBuilder {
   }
   /**
    * Transforms values into JSON format.
+   *
+   * @param {array[]} rows Rows to convert to JSON.
+   * @returns {object[]}
    */
   toJSON(rows) {
     return rows.map(values => {
@@ -116,6 +125,9 @@ class RowBuilder {
   }
   /**
    * Extracts value from chunk.
+   *
+   * @param {object} obj Row value object.
+   * @returns {*}
    */
   static getValue(obj) {
     let value = obj;
@@ -130,6 +142,10 @@ class RowBuilder {
   /**
    * Format a value into the expected structure, e.g. turn struct values into an
    * object.
+   *
+   * @param {object} field Field object
+   * @param {*} value Field value
+   * @returns {*}
    */
   static formatValue(field, value) {
     if (value === 'NULL_VALUE') {
@@ -150,6 +166,11 @@ class RowBuilder {
   }
   /**
    * Merge chunk values.
+   *
+   * @param {object} type Field type
+   * @param {object} head Field value
+   * @param {object} tail Field value
+   * @return {array}
    */
   static merge(type, head, tail) {
     const code = type.code;

src/session.js

@@ -360,6 +360,7 @@ class Session extends ServiceObject {
    *
    * @param {string} databaseName The parent database's name.
    * @param {string} name The instance name.
+   * @returns {string}
    *
    * @example
    * Session.formatName_('my-database', 'my-session');

src/table.js

@@ -129,7 +129,6 @@ class Table extends TransactionRequest {
    * @see [StreamingRead API Documentation](https://cloud.google.com/spanner/docs/reference/rpc/google.spanner.v1#google.spanner.v1.Spanner.StreamingRead)
    * @see [ReadRequest API Documentation](https://cloud.google.com/spanner/docs/reference/rpc/google.spanner.v1#google.spanner.v1.ReadRequest)
    *
-   * @param {string} table The table to read from.
    * @param {ReadStreamRequestOptions} query Configuration object. See
    *     [`ReadRequest`](https://cloud.google.com/spanner/docs/reference/rpc/google.spanner.v1#google.spanner.v1.ReadRequest).
    * @param {TransactionOptions} [options] [Transaction options](https://cloud.google.com/spanner/docs/timestamp-bounds).
@@ -387,7 +386,6 @@ class Table extends TransactionRequest {
    */
   /**
    * @typedef {array} TableReadResponse
-   * @property {Table} 0 The new {@link Table}.
    * @property {array[]} 1 Rows are returned as an array of object arrays. Each
    *     object has a `name` and `value` property. To get a serialized object,
    *     call `toJSON()`. Optionally, provide an options object to `toJSON()`
@@ -515,13 +513,13 @@ class Table extends TransactionRequest {
    * region_tag:spanner_read_data_with_storing_index
    * Reading data using a storing index:
    */
-  read(keyVals, options, callback) {
+  read(query, options, callback) {
     const rows = [];
     if (is.fn(options)) {
       callback = options;
       options = null;
     }
-    this.createReadStream(keyVals, options)
+    this.createReadStream(query, options)
       .on('error', callback)
       .on('data', function(row) {
         rows.push(row);