Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: add documentation for callback arguments #738

Merged
merged 1 commit into from
Jul 24, 2015
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 17 additions & 0 deletions lib/bigquery/dataset.js
Original file line number Diff line number Diff line change
Expand Up @@ -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.

This comment was marked as spam.

This comment was marked as spam.

This comment was marked as spam.

This comment was marked as spam.

* @param {object} callback.apiResponse - The full API response.
*
* @example
* var tableConfig = {
Expand Down Expand Up @@ -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
* //-
Expand Down Expand Up @@ -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) {});
Expand All @@ -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) {
Expand Down Expand Up @@ -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 = {
Expand Down
28 changes: 26 additions & 2 deletions lib/bigquery/index.js
Original file line number Diff line number Diff line change
Expand Up @@ -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) {});
Expand Down Expand Up @@ -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) {
Expand Down Expand Up @@ -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) {
Expand Down Expand Up @@ -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';
Expand Down Expand Up @@ -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.
Expand Down
8 changes: 8 additions & 0 deletions lib/bigquery/job.js
Original file line number Diff line number Diff line change
Expand Up @@ -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');
Expand Down Expand Up @@ -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) {
Expand Down
25 changes: 25 additions & 0 deletions lib/bigquery/table.js
Original file line number Diff line number Diff line change
Expand Up @@ -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.
*
Expand Down Expand Up @@ -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) {});
Expand All @@ -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.
Expand Down Expand Up @@ -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) {});
Expand Down Expand Up @@ -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) {
Expand Down Expand Up @@ -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.
*
Expand Down Expand Up @@ -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
* //-
Expand Down Expand Up @@ -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 = {
Expand Down
4 changes: 4 additions & 0 deletions lib/datastore/dataset.js
Original file line number Diff line number Diff line change
Expand Up @@ -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) {
Expand Down
16 changes: 16 additions & 0 deletions lib/datastore/request.js
Original file line number Diff line number Diff line change
Expand Up @@ -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
* //-
Expand Down Expand Up @@ -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
* //-
Expand Down Expand Up @@ -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
* //-
Expand Down Expand Up @@ -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
* //-
Expand Down Expand Up @@ -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
* //-
Expand Down
4 changes: 3 additions & 1 deletion lib/datastore/transaction.js
Original file line number Diff line number Diff line change
Expand Up @@ -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.
* }
Expand Down
3 changes: 3 additions & 0 deletions lib/pubsub/index.js
Original file line number Diff line number Diff line change
Expand Up @@ -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
* //-
Expand Down
5 changes: 5 additions & 0 deletions lib/search/document.js
Original file line number Diff line number Diff line change
Expand Up @@ -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) {});
Expand All @@ -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) {
Expand Down
15 changes: 14 additions & 1 deletion lib/search/index-class.js
Original file line number Diff line number Diff line change
Expand Up @@ -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
* //-
Expand Down Expand Up @@ -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) {
Expand Down Expand Up @@ -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';
Expand Down
5 changes: 5 additions & 0 deletions lib/search/index.js
Original file line number Diff line number Diff line change
Expand Up @@ -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) {
Expand Down
Loading