streamrouter: document methods to instruct user on how to exit early

lib/bigquery/index.js

@@ -168,9 +168,14 @@ BigQuery.prototype.dataset = function(id) {
  * @param {function} callback - The callback function.
  *
  * @example
- * bigquery.getDatasets(function(err, datasets, nextQuery, apiResponse) {
- *   // If `nextQuery` is non-null, there are more results to fetch.
- * });
+ * var callback = function(err, datasets, nextQuery, apiResponse) {
+ *   if (nextQuery) {
+ *     // More results exist.
+ *     bigquery.getDatasets(nextQuery, callback);
+ *   }
+ * };
+ *
+ * bigquery.getDatasets(callback);
  *
  * //-
  * // Get the datasets from your project as a readable object stream.
@@ -183,6 +188,15 @@ BigQuery.prototype.dataset = function(id) {
  *   .on('end', function() {
  *     // All datasets retrieved.
  *   });
+ *
+ * //-
+ * // If you anticipate many results, you can end a stream early to prevent
+ * // unnecessary processing and API requests.
+ * //-
+ * bigquery.getDatasets()
+ *   .on('data', function(dataset) {
+ *     this.end();
+ *   });
  */
 BigQuery.prototype.getDatasets = function(query, callback) {
   var that = this;
@@ -250,6 +264,15 @@ BigQuery.prototype.getDatasets = function(query, callback) {
  *   .on('end', function() {
  *     // All jobs retrieved.
  *   });
+ *
+ * //-
+ * // If you anticipate many results, you can end a stream early to prevent
+ * // unnecessary processing and API requests.
+ * //-
+ * bigquery.getJobs()
+ *   .on('data', function(job) {
+ *     this.end();
+ *   });
  */
 BigQuery.prototype.getJobs = function(options, callback) {
   var that = this;
@@ -330,14 +353,15 @@ BigQuery.prototype.job = function(id) {
  * //-
  * // You can run a query against your data in a serial manner.
  * //-
- * bigquery.query(query, function(err, rows, nextQuery, apiResponse) {
+ * var callback = function(err, rows, nextQuery, apiResponse) {
  *   // Handle results here.
+ *
  *   if (nextQuery) {
- *     bigquery.query(nextQuery, function(err, rows, nextQuery, apiResponse) {
- *       // Handle more results here.
- *     });
+ *     bigquery.query(nextQuery, callback);
  *   }
- * });
+ * };
+ *
+ * bigquery.query(query, callback);
  *
  * //-
  * // You can also use the `query` method as a readable object stream by

lib/bigquery/table.js

@@ -491,12 +491,14 @@ Table.prototype.getMetadata = function(callback) {
  *   maxResults: 100
  * };
  *
- * table.getRows(options, function(err, rows, nextQuery, apiResponse) {
- *   // If `nextQuery` is non-null, there are more results to fetch.
+ * var callback = function(err, rows, nextQuery, apiResponse) {
  *   if (nextQuery) {
- *     table.getRows(nextQuery, function(err, rows, nextQuery, apiResponse) {});
+ *     // More results exist.
+ *     table.getRows(nextQuery, callback);
  *   }
- * });
+ * };
+ *
+ * table.getRows(options, callback);
  *
  * //-
  * // Get the rows as a readable object stream.
@@ -507,6 +509,15 @@ Table.prototype.getMetadata = function(callback) {
  *   .on('end', function() {
  *     // All rows have been retrieved.
  *   });
+ *
+ * //-
+ * // If you anticipate many results, you can end a stream early to prevent
+ * // unnecessary processing and API requests.
+ * //-
+ * table.getRows()
+ *   .on('data', function(row) {
+ *     this.end();
+ *   });
  */
 Table.prototype.getRows = function(options, callback) {
   var that = this;

lib/pubsub/index.js

@@ -139,6 +139,15 @@ function PubSub(options) {
  *   .on('end', function() {
  *     // All topics retrieved.
  *   });
+ *
+ * //-
+ * // If you anticipate many results, you can end a stream early to prevent
+ * // unnecessary processing and API requests.
+ * //-
+ * pubsub.getTopics()
+ *   .on('data', function(topic) {
+ *     this.end();
+ *   });
  */
 PubSub.prototype.getTopics = function(query, callback) {
   var self = this;
@@ -440,6 +449,15 @@ PubSub.prototype.topic = function(name, options) {
  *   .on('end', function() {
  *     // All subscriptions retrieved.
  *   });
+ *
+ * //-
+ * // If you anticipate many results, you can end a stream early to prevent
+ * // unnecessary processing and API requests.
+ * //-
+ * pubsub.getSubscriptions()
+ *   .on('data', function(topic) {
+ *     this.end();
+ *   });
  */
 PubSub.prototype.getSubscriptions = function(options, callback) {
   var self = this;

lib/pubsub/topic.js

@@ -218,6 +218,15 @@ Topic.prototype.delete = function(callback) {
  *   .on('end', function() {
  *     // All subscriptions retrieved.
  *   });
+ *
+ * //-
+ * // If you anticipate many results, you can end a stream early to prevent
+ * // unnecessary processing and API requests.
+ * //-
+ * topic.getSubscriptions()
+ *   .on('data', function(subscription) {
+ *     this.end();
+ *   });
  */
 Topic.prototype.getSubscriptions = function(options, callback) {
   if (util.is(options, 'function')) {

lib/search/index-class.js

@@ -190,6 +190,15 @@ Index.prototype.document = function(id) {
  *   .on('end', function() {
  *     // All documents retrieved.
  *   });
+ *
+ * //-
+ * // If you anticipate many results, you can end a stream early to prevent
+ * // unnecessary processing and API requests.
+ * //-
+ * index.getDocuments()
+ *   .on('data', function(document) {
+ *     this.end();
+ *   });
  */
 Index.prototype.getDocuments = function(query, callback) {
   var self = this;

lib/search/index.js

@@ -138,6 +138,15 @@ function Search(options) {
  *   .on('end', function() {
  *     // All indexes retrieved.
  *   });
+ *
+ * //-
+ * // If you anticipate many results, you can end a stream early to prevent
+ * // unnecessary processing and API requests.
+ * //-
+ * search.getIndexes()
+ *   .on('data', function(index) {
+ *     this.end();
+ *   });
  */
 Search.prototype.getIndexes = function(query, callback) {
   var self = this;

lib/storage/bucket.js

@@ -514,6 +514,15 @@ Bucket.prototype.file = function(name, options) {
  *   .on('end', function() {
  *     // All files retrieved.
  *   });
+ *
+ * //-
+ * // If you anticipate many results, you can end a stream early to prevent
+ * // unnecessary processing and API requests.
+ * //-
+ * bucket.getFiles()
+ *   .on('data', function(file) {
+ *     this.end();
+ *   });
  */
 Bucket.prototype.getFiles = function(query, callback) {
   var self = this;

lib/storage/index.js

@@ -290,6 +290,15 @@ Storage.prototype.createBucket = function(name, metadata, callback) {
  *   .on('end', function() {
  *     // All buckets retrieved.
  *   });
+ *
+ * //-
+ * // If you anticipate many results, you can end a stream early to prevent
+ * // unnecessary processing and API requests.
+ * //-
+ * gcs.getBuckets()
+ *   .on('data', function(bucket) {
+ *     this.end();
+ *   });
  */
 Storage.prototype.getBuckets = function(query, callback) {
   var that = this;