docs: add documentation for ending streams early (#1263)

Author: callmehiphop

lib/bigquery/index.js

@@ -457,6 +457,15 @@ BigQuery.prototype.job = function(id) {
  *   .on('end', function() {
  *     // All rows retrieved.
  *   });
+ *
+ * //-
+ * // If you anticipate many results, you can end a stream early to prevent
+ * // unnecessary processing and API requests.
+ * //-
+ * bigquery.query(query)
+ *   .on('data', function(row) {
+ *     this.end();
+ *   });
  */
 BigQuery.prototype.query = function(options, callback) {
   var that = this;

lib/datastore/request.js

@@ -413,6 +413,15 @@ DatastoreRequest.prototype.insert = function(entities, callback) {
  *   });
  *
  * //-
+ * // If you anticipate many results, you can end a stream early to prevent
+ * // unnecessary processing and API requests.
+ * //-
+ * datastore.runQuery(query)
+ *   .on('data', function (entity) {
+ *     this.end();
+ *   });
+ *
+ * //-
  * // A keys-only query returns just the keys of the result entities instead of
  * // the entities themselves, at lower latency and cost.
  * //-

lib/dns/index.js

@@ -171,6 +171,27 @@ DNS.prototype.createZone = function(name, config, callback) {
  *
  * @example
  * dns.getZones(function(err, zones, apiResponse) {});
+ *
+ * //-
+ * // Get the zones from your project as a readable object stream.
+ * //-
+ * dns.getZones()
+ *   .on('error', console.error)
+ *   .on('data', function(zone) {
+ *     // zone is a Zone object.
+ *   })
+ *   .on('end', function() {
+ *     // All zones retrieved.
+ *   });
+ *
+ * //-
+ * // If you anticipate many results, you can end a stream early to prevent
+ * // unnecessary processing and API requests.
+ * //-
+ * dns.getZones()
+ *   .on('data', function(zone) {
+ *     this.end();
+ *   });
  */
 DNS.prototype.getZones = function(query, callback) {
   var self = this;

lib/logging/index.js

@@ -411,6 +411,15 @@ Logging.prototype.getEntries = function(options, callback) {
  *   .on('end', function() {
  *     // All sinks retrieved.
  *   });
+ *
+ * //-
+ * // If you anticipate many results, you can end a stream early to prevent
+ * // unnecessary processing and API requests.
+ * //-
+ * logging.getSinks()
+ *   .on('data', function(sink) {
+ *     this.end();
+ *   });
  */
 Logging.prototype.getSinks = function(options, callback) {
   var self = this;