docs: add documentation for callback arguments

lib/bigquery/dataset.js

@@ -64,6 +64,9 @@ function Dataset(bigQuery, id) {
  *     JSON array of fields, which allows for nested and repeated fields. See
  *     a [Table resource](http://goo.gl/sl8Dmg) for more detailed information.
  * @param {function} callback - The callback function.
+ * @param {?error} callback.err - An error returned while making this request
+ * @param {module:bigquery/table} callback.table - The newly created table.
+ * @param {object} callback.apiResponse - The full API response.
  *
  * @example
  * var tableConfig = {
@@ -117,6 +120,8 @@ Dataset.prototype.createTable = function(options, callback) {
  * @param {boolean} options.force - Force delete dataset and all tables.
  *     Default: false.
  * @param {function} callback - The callback function.
+ * @param {?error} callback.err - An error returned while making this request
+ * @param {object} callback.apiResponse - The full API response.
  *
  * @example
  * //-
@@ -146,6 +151,9 @@ Dataset.prototype.delete = function(options, callback) {
  * Get the metadata for the Dataset.
  *
  * @param {function} callback - The callback function.
+ * @param {?error} callback.err - An error returned while making this request
+ * @param {object} callback.metadata - The Dataset metadata
+ * @param {object} callback.apiResponse - The full API response.
  *
  * @example
  * dataset.getMetadata(function(err, metadata, apiResponse) {});
@@ -172,6 +180,12 @@ Dataset.prototype.getMetadata = function(callback) {
  * @param {string} query.pageToken - Token returned from a previous call, to
  *     request the next page of results.
  * @param {function} callback - The callback function.
+ * @param {?error} callback.err - An error returned while making this request
+ * @param {module:bigquery/table[]} callback.tables - The list of tables from
+ *     your Dataset.
+ * @param {?object} callback.nextQuery - If present, query with this object to
+ *     check for more results.
+ * @param {object} callback.apiResponse - The full API response.
  *
  * @example
  * dataset.getTables(function(err, tables, nextQuery, apiResponse) {
@@ -238,6 +252,9 @@ Dataset.prototype.query = function(options, callback) {
  *
  * @param {object} metadata - Metadata to save on the Dataset.
  * @param {function} callback - The callback function.
+ * @param {?error} callback.err - An error returned while making this request
+ * @param {object} callback.metadata - The metadata of the Dataset object.
+ * @param {object} callback.apiResponse - The full API response.
  *
  * @example
  * var metadata = {

lib/bigquery/index.js

@@ -119,6 +119,9 @@ function BigQuery(options) {
  *
  * @param {string} id - ID of the dataset to create.
  * @param {function} callback  - The callback function.
+ * @param {?error} callback.err - An error returned while making this request
+ * @param {module:bigquery/dataset} callback.dataset - The newly created dataset
+ * @param {object} callback.apiResponse - The full API response.
  *
  * @example
  * bigquery.createDataset('my-dataset', function(err, dataset, apiResponse) {});
@@ -168,7 +171,13 @@ BigQuery.prototype.dataset = function(id) {
  * @param {number} query.maxResults - Maximum number of results to return.
  * @param {string} query.pageToken - Token returned from a previous call, to
  *     request the next page of results.
- * @param {function} callback - The callback function.
+ * @param {function=} callback - The callback function.
+ * @param {?error} callback.err - An error returned while making this request
+ * @param {module:bigquery/dataset[]} callback.datasets - The list of datasets
+ *     in your project.
+ * @param {?object} callback.nextQuery - If present, query with this object to
+ *     check for more results.
+ * @param {object} callback.apiResponse - The full API response.
  *
  * @example
  * bigquery.getDatasets(function(err, datasets) {
@@ -263,7 +272,13 @@ BigQuery.prototype.getDatasets = function(query, callback) {
  *     "minimal", to not include the job configuration.
  * @param {string=} options.stateFilter - Filter for job state. Acceptable
  *     values are "done", "pending", and "running".
- * @param {function} callback - The callback function.
+ * @param {function=} callback - The callback function.
+ * @param {?error} callback.err - An error returned while making this request
+ * @param {module:bigquery/job[]} callback.jobs - The list of jobs in your
+ *     project.
+ * @param {?object} callback.nextQuery - If present, query with this object to
+ *     check for more results.
+ * @param {object} callback.apiResponse - The full API response.
  *
  * @example
  * bigquery.getJobs(function(err, jobs) {
@@ -380,6 +395,11 @@ BigQuery.prototype.job = function(id) {
  *     immediately. If the timeout passes before the job completes, the request
  *     will fail with a `TIMEOUT` error.
  * @param {function=} callback - The callback function.
+ * @param {?error} callback.err - An error returned while making this request
+ * @param {array} callback.rows - The list of results from your query.
+ * @param {?object} callback.nextQuery - If present, query with this object to
+ *     check for more results.
+ * @param {object} callback.apiResponse - The full API response.
  *
  * @example
  * var query = 'SELECT url FROM [publicdata:samples.github_nested] LIMIT 100';
@@ -488,6 +508,10 @@ BigQuery.prototype.query = function(options, callback) {
  * @param {string} options.query - A query string, following the BigQuery query
  *     syntax, of the query to execute.
  * @param {function} callback - The callback function.
+ * @param {?error} callback.err - An error returned while making this request.
+ * @param {module:bigquery/job} callback.job - The newly created job for your
+       query.
+ * @param {object} callback.apiResponse - The full API response.
  *
  * @throws {Error} If a query is not specified.
  * @throws {Error} If a Table is not provided as a destination.

lib/bigquery/job.js

@@ -65,6 +65,9 @@ function Job(bigQuery, id) {
  * status of a previously-run job.
  *
  * @param {function} callback - The callback function.
+ * @param {?error} callback.err - An error returned while making this request
+ * @param {object} callback.metadata - The metadata of the job.
+ * @param {object} callback.apiResponse - The full API response.
  *
  * @example
  * var job = bigquery.job('id');
@@ -105,6 +108,11 @@ Job.prototype.getMetadata = function(callback) {
  * @param {function=} callback - The callback function. If you intend to
  *     continuously run this query until all results are in as part of a stream,
  *     do not pass a callback.
+ * @param {?error} callback.err - An error returned while making this request
+ * @param {array} callback.rows - The results of a job.
+ * @param {?object} callback.nextQuery - If present, query with this object to
+ *     check for more results.
+ * @param {object} callback.apiResponse - The full API response.
  *
  * @example
  * var callback = function(err, rows, nextQuery, apiResponse) {

lib/bigquery/table.js

@@ -135,6 +135,9 @@ Table.mergeSchemaWithRows_ = function(schema, rows) {
  *     metadata object should be in the format of the
  *     [`configuration.copy`](http://goo.gl/dKWIyS) property of a Jobs resource.
  * @param {function} callback - The callback function.
+ * @param {?error} callback.err - An error returned while making this request
+ * @param {module:bigquery/job} callback.job - The job used to copy your table.
+ * @param {object} callback.apiResponse - The full API response.
  *
  * @throws {Error} If a destination other than a Table object is provided.
  *
@@ -327,6 +330,8 @@ Table.prototype.createWriteStream = function(metadata) {
  * Delete a table and all its data.
  *
  * @param {function} callback - The callback function.
+ * @param {?error} callback.err - An error returned while making this request
+ * @param {object} callback.apiResponse - The full API response.
  *
  * @example
  * table.delete(function(err, apiResponse) {});
@@ -346,6 +351,9 @@ Table.prototype.delete = function(callback) {
  * @param {boolean} options.gzip - Specify if you would like the file compressed
  *     with GZIP. Default: false.
  * @param {function} callback - The callback function.
+ * @param {?error} callback.err - An error returned while making this request
+ * @param {module:bigquery/job} callback.job - The job used to export the table.
+ * @param {object} callback.apiResponse - The full API response.
  *
  * @throws {Error} If destination isn't a File object.
  * @throws {Error} If destination format isn't recongized.
@@ -459,6 +467,9 @@ Table.prototype.export = function(destination, options, callback) {
  * Return the metadata associated with the Table.
  *
  * @param {function} callback - The callback function.
+ * @param {?error} callback.err - An error returned while making this request
+ * @param {object} callback.metadata - The metadata of the Table.
+ * @param {object} callback.apiResponse - The full API response.
  *
  * @example
  * table.getMetadata(function(err, metadata, apiResponse) {});
@@ -487,6 +498,11 @@ Table.prototype.getMetadata = function(callback) {
  *     automatically. Default: true.
  * @param {number} options.maxResults - Maximum number of results to return.
  * @param {function} callback - The callback function.
+ * @param {?error} callback.err - An error returned while making this request
+ * @param {array} callback.rows - The table data from specified set of rows.
+ * @param {?object} callback.nextQuery - If present, query with this object to
+ *     check for more results.
+ * @param {object} callback.apiResponse - The full API response.
  *
  * @example
  * table.getRows(function(err, rows) {
@@ -598,6 +614,9 @@ Table.prototype.getRows = function(options, callback) {
  *     metadata object should be in the format of the
  *     [`configuration.load`](http://goo.gl/BVcXk4) property of a Jobs resource.
  * @param {function} callback - The callback function.
+ * @param {?error} callback.err - An error returned while making this request
+ * @param {module:bigquery/job} callback.job - The job used to import your data.
+ * @param {object} callback.apiResponse - The full API response.
  *
  * @throws {Error} If the source isn't a string file name or a File instance.
  *
@@ -720,6 +739,9 @@ Table.prototype.import = function(source, metadata, callback) {
  *
  * @param {object|object[]} rows - The rows to insert into the table.
  * @param {function} callback - The callback function.
+ * @param {?error} callback.err - An error returned while making this request.
+ * @param {array} callback.insertErrors - A list of errors for insert failures.
+ * @param {object} callback.apiResponse - The full API response.
  *
  * @example
  * //-
@@ -822,6 +844,9 @@ Table.prototype.query = function(query, callback) {
  *     JSON array of fields, which allows for nested and repeated fields. See
  *     a [Table resource](http://goo.gl/sl8Dmg) for more detailed information.
  * @param {function} callback - The callback function.
+ * @param {?error} callback.err - An error returned while making this request.
+ * @param {object} callback.metadata - The metadata of the Table.
+ * @param {object} callback.apiResponse - The full API response.
  *
  * @example
  * var metadata = {

lib/datastore/dataset.js

@@ -222,7 +222,11 @@ Dataset.prototype.createQuery = function(namespace, kind) {
  * @borrows {module:datastore/transaction#begin} as runInTransaction
  *
  * @param {function} fn - The function to run in the context of a transaction.
+ * @param {module:datastore/transaction} fn.transaction - The Transaction.
+ * @param {function} fn.done - Function used to commit changes.
  * @param {function} callback - The callback function.
+ * @param {?error} callback.err - An error returned while making this request
+ *
  *
  * @example
  * dataset.runInTransaction(function(transaction, done) {

lib/datastore/request.js

@@ -94,6 +94,10 @@ function DatastoreRequest() {}
  *
  * @param {Key|Key[]} keys - Datastore key object(s).
  * @param {function} callback - The callback function.
+ * @param {?error} callback.err - An error returned while making this request
+ * @param {module:datastore/entity|module:datastore/entity[]} callback.entity -
+ *     Will return either a single Entity or a list of Entities
+ * @param {object} callback.apiResponse - The full API response.
  *
  * @example
  * //-
@@ -188,6 +192,8 @@ DatastoreRequest.prototype.insert = function(entities, callback) {
  *     `name` for the name of the property and `value` for its value. You may
  *     also specify an `excludeFromIndexes` property, set to `true` or `false`.
  * @param {function} callback - The callback function.
+ * @param {?error} callback.err - An error returned while making this request
+ * @param {object} callback.apiResponse - The full API response.
  *
  * @example
  * //-
@@ -430,6 +436,8 @@ DatastoreRequest.prototype.save = function(entities, callback) {
  *
  * @param {Key|Key[]} key - Datastore key object(s).
  * @param {function} callback - The callback function.
+ * @param {?error} callback.err - An error returned while making this request
+ * @param {object} callback.apiResponse - The full API response.
  *
  * @example
  * //-
@@ -489,6 +497,11 @@ DatastoreRequest.prototype.delete = function(keys, callback) {
  * @param {?module:datastore/query} callback.nextQuery - If present, run another
  *     query with this object to check for more results.
  * @param {object} callback.apiResponse - The full API response.
+ * @param {?error} callback.err - An error returned while making this request
+ * @param {module:datastore/entity[]} callback.entities - A list of Entities
+ * @param {?object} callback.nextQuery - If present, query with this object to
+ *     check for more results.
+ * @param {object} callback.apiResponse - The full API response.
  *
  * @example
  * //-
@@ -577,6 +590,9 @@ DatastoreRequest.prototype.runQuery = function(query, callback) {
  * @param {Key} incompleteKey - The key object to complete.
  * @param {number} n - How many IDs to generate.
  * @param {function} callback - The callback function.
+ * @param {?error} callback.err - An error returned while making this request
+ * @param {array} callback.keys - The generated IDs
+ * @param {object} callback.apiResponse - The full API response.
  *
  * @example
  * //-

lib/datastore/transaction.js

@@ -121,9 +121,11 @@ Transaction.prototype.begin_ = function(callback) {
  * Reverse a transaction remotely and finalize the current transaction instance.
  *
  * @param {function} callback - The callback function.
+ * @param {?error} callback.err - An error returned while making this request
+ * @param {object} callback.apiResponse - The full API response.
  *
  * @example
- * transaction.rollback(function(err) {
+ * transaction.rollback(function(err, apiResponse) {
  *   if (err) {
  *     // Transaction could not be rolled back.
  *   }

lib/pubsub/index.js

@@ -248,6 +248,9 @@ PubSub.prototype.createTopic = function(name, callback) {
  *     false, attempting to create a subscription that already exists will fail.
  *     (default: false)
  * @param {function} callback - The callback function.
+ * @param {?error} callback.err - An error returned while making this request
+ * @param {module:pubsub/subscription} callback.subscription - The subscription.
+ * @param {object} callback.apiResponse - The full API response.
  *
  * @example
  * //-

lib/search/document.js

@@ -83,6 +83,8 @@ Document.prototype.addField = function(name) {
  * Delete this document.
  *
  * @param {function=} callback - The callback function.
+ * @param {?error} callback.err - An error returned while making this request
+ * @param {object} callback.apiResponse - The full API response.
  *
  * @example
  * document.delete(function(err, apiResponse) {});
@@ -99,6 +101,9 @@ Document.prototype.delete = function(callback) {
  * time of this call.
  *
  * @param {function} callback - The callback function.
+ * @param {?error} callback.err - An error returned while making this request
+ * @param {module:search/document} callback.doc - The Document reference.
+ * @param {object} callback.apiResponse - The full API response.
  *
  * @example
  * document.getMetadata(function(err, doc, apiResponse) {

lib/search/index-class.js

@@ -73,6 +73,9 @@ function Index(search, id) {
  *     Document object as outlined in the
  *     [official docs](https://goo.gl/AYhSgI).
  * @param {function} callback - The callback function.
+ * @param {?error} callback.err - An error returned while making this request
+ * @param {module:search/document} callback.document - The Document object.
+ * @param {object} callback.apiResponse - The full API response.
  *
  * @example
  * //-
@@ -156,7 +159,12 @@ Index.prototype.document = function(id) {
  *     representing part of the larger set of results to view.
  * @param {string} query.view - One of `INDEX_VIEW_UNSPECIFIED`, `ID_ONLY`, or
  *     `FULL`. See [this table](https://goo.gl/sY6Lpt) for more details.
- * @param {function} callback - The callback function.
+ * @param {function=} callback - The callback function.
+ * @param {?error} callback.err - An error returned while making this request
+ * @param {module:search/document[]} callback.documents - A list of Documents.
+ * @param {?object} callback.nextQuery - If present, query with this object to
+ *     check for more results.
+ * @param {object} callback.apiResponse - The full API response.
  *
  * @example
  * index.getDocuments(function(err, documents) {
@@ -254,6 +262,11 @@ Index.prototype.getDocuments = function(query, callback) {
  * @param {string} query.query = A query string using the syntax described by
  *     the [official docs](https://goo.gl/2SYl3S).
  * @param {function} callback - The callback function.
+ * @param {?error} callback.err - An error returned while making this request
+ * @param {module:search/document[]} callback.documents - A list of Documents
+ * @param {?object} callback.nextQuery - If present, query with this object to
+ *     check for more results.
+ * @param {object} callback.apiResponse - The full API response.
  *
  * @example
  * var query = 'person:stephen';

lib/search/index.js

@@ -107,6 +107,11 @@ function Search(options) {
  * @param {string} query.view - See [this table](https://goo.gl/sY6Lpt) for a
  *     list of accepted values and what each will do.
  * @param {function} callback - The callback function.
+ * @param {?error} callback.err - An error returned while making this request
+ * @param {module:search/index[]} callback.indexes - A list of Indexes.
+ * @param {?object} callback.nextQuery - If present, query with this object to
+ *     check for more results.
+ * @param {object} callback.apiResponse - The full API response.
  *
  * @example
  * search.getIndexes(function(err, indexes) {