docs: generate uniform service overviews (googleapis#1475)

package.json

@@ -29,7 +29,7 @@
     "docs": "node ./scripts/docs/packages.js",
     "bundle": "node ./scripts/docs/bundle.js",
     "lint": "jshint scripts/ packages/ system-test/ test/ && jscs packages/ system-test/ test/",
-    "test": "npm run docs && mocha test/docs.js packages/*/test/*.js",
+    "test": "npm run docs && npm run bundle && mocha test/docs.js packages/*/test/*.js",
     "system-test": "mocha packages/*/system-test/*.js --no-timeouts --bail",
     "cover": "istanbul cover _mocha --report lcovonly -- --no-timeouts --bail packages/*/test/*.js -R spec",
     "coveralls": "npm run cover && cat ./coverage/lcov.info | ./node_modules/coveralls/bin/coveralls.js && rm -rf ./coverage"

packages/bigquery/src/dataset.js

@@ -44,12 +44,6 @@ var Table = require('./table.js');
  * @constructor
  *
  * @example
- * var gcloud = require('google-cloud');
- *
- * var bigquery = gcloud.bigquery({
- *   keyFilename: '/path/to/keyfile.json',
- *   projectId: 'grape-spaceship-123'
- * });
  * var dataset = bigquery.dataset('institutions');
  */
 function Dataset(bigQuery, id) {

packages/bigquery/src/index.js

@@ -46,39 +46,19 @@ var Table = require('./table.js');
 var PKG = require('../package.json');
 
 /**
- * The examples below will demonstrate the different usage patterns your app may
- * need to support to retrieve a BigQuery object.
+ * In the following examples from this page and the other modules (`Dataset`,
+ * `Table`, etc.), we are going to be using a dataset from
+ * [data.gov](http://goo.gl/f2SXcb) of higher education institutions.
+ *
+ * We will create a table with the correct schema, import the public CSV file
+ * into that table, and query it for data.
  *
  * @alias module:bigquery
  * @constructor
  *
- * @classdesc
- * The object returned from `gcloud.bigquery` gives you complete access to and
- * control of your BigQuery datasets. You can work with existing ones, by using
- * the `dataset` method, or create new ones with `createDataset`.
- *
- * To learn more about BigQuery, see
- * [What is BigQuery?](https://cloud.google.com/bigquery/what-is-bigquery)
+ * @resource [What is BigQuery?]{@link https://cloud.google.com/bigquery/what-is-bigquery}
  *
  * @param {object} options - [Configuration object](#/docs).
- *
- * @example
- * var gcloud = require('google-cloud')({
- *   keyFilename: '/path/to/keyfile.json',
- *   projectId: 'my-project'
- * });
- *
- * var bigquery = gcloud.bigquery();
- *
- * //-
- * // In the following examples from this page and the other modules (Dataset,
- * // Table, etc.), we are going to be using a dataset from
- * // <a href="http://goo.gl/f2SXcb">data.gov</a> of higher education
- * // institutions.
- * //
- * // We will create a table with the correct schema, import the public CSV
- * // file into that table, and query it for data.
- * //-
  */
 function BigQuery(options) {
   if (!(this instanceof BigQuery)) {

packages/bigquery/src/job.js

@@ -29,11 +29,6 @@ var modelo = require('modelo');
  *
  * @param {module:bigquery} bigQuery - BigQuery instance.
  * @param {string} id - The ID of the job.
- *
- * @example
- * var bigquery = gcloud.bigquery({ projectId: 'grape-spaceship-123' });
- * var Job = require('gcloud/lib/bigquery/job');
- * var job = new Job(bigquery, 'job-id');
  */
 /**
  * Job objects are returned from various places in the BigQuery API:
@@ -54,13 +49,6 @@ var modelo = require('modelo');
  * @constructor
  *
  * @example
- * var gcloud = require('google-cloud')({
- *   keyFilename: '/path/to/keyfile.json',
- *   projectId: 'grape-spaceship-123'
- * });
- *
- * var bigquery = gcloud.bigquery();
- *
  * var job = bigquery.job('job-id');
  *
  * //-

packages/bigquery/src/table.js

@@ -48,13 +48,6 @@ var FORMATS = {
  *
  * @param {module:bigquery/dataset} dataset - Dataset instance.
  * @param {string} id - The ID of the table.
- *
- * @example
- * var bigquery = gcloud.bigquery({ projectId: 'grape-spaceship-123' });
- * var Dataset = require('gcloud/lib/bigquery/dataset');
- * var dataset = new Dataset(bigquery, 'dataset-id');
- * var Table = require('gcloud/lib/bigquery/table');
- * var table = new Table(dataset, 'table-id');
  */
 /**
  * Table objects are returned by methods such as
@@ -65,13 +58,6 @@ var FORMATS = {
  * @constructor
  *
  * @example
- * var gcloud = require('google-cloud')({
- *   keyFilename: '/path/to/keyfile.json',
- *   projectId: 'grape-spaceship-123'
- * });
- *
- * var bigquery = gcloud.bigquery();
- *
  * var dataset = bigquery.dataset('my-dataset');
  *
  * var table = dataset.table('my-table');
@@ -473,7 +459,7 @@ Table.prototype.createWriteStream = function(metadata) {
  * @throws {Error} If destination format isn't recongized.
  *
  * @example
- * var gcs = gcloud.storage({
+ * var gcs = require('@google-cloud/storage')({
  *   projectId: 'grape-spaceship-123'
  * });
  * var exportedFile = gcs.bucket('institutions').file('2014.csv');

packages/bigtable/src/family.js

@@ -40,15 +40,6 @@ var FamilyError = createErrorClass('FamilyError', function(name) {
  * @alias module:bigtable/family
  *
  * @example
- * var gcloud = require('google-cloud');
- *
- * var bigtable = gcloud.bigtable({
- *   keyFilename: '/path/to/keyfile.json',
- *   projectId: 'grape-spaceship-123',
- *   cluster: 'gcloud-node',
- *   zone: 'us-central1-b'
- * });
- *
  * var table = bigtable.table('prezzy');
  * var family = table.family('follows');
  */

packages/bigtable/src/index.js

@@ -42,19 +42,11 @@ var Table = require('./table.js');
 var PKG = require('../package.json');
 
 /**
- * Interact with
- * [Google Cloud Bigtable](https://cloud.google.com/bigtable/).
- *
- * @constructor
  * @alias module:bigtable
- *
- * @classdesc
- * The `gcloud.bigtable` object allows you interact with Google Cloud Bigtable.
- *
- * To learn more about Bigtable, read the
- * [Google Cloud Bigtable Concepts Overview](https://cloud.google.com/bigtable/docs/concepts)
+ * @constructor
  *
  * @resource [Creating a Cloud Bigtable Cluster]{@link https://cloud.google.com/bigtable/docs/creating-compute-instance}
+ * @resource [Google Cloud Bigtable Concepts Overview]{@link https://cloud.google.com/bigtable/docs/concepts}
  *
  * @throws {error} If a cluster is not provided.
  * @throws {error} If a zone is not provided.
@@ -64,17 +56,6 @@ var PKG = require('../package.json');
  * @param {string|module:compute/zone} options.zone - The zone in which your
  *     cluster resides.
  *
- * @example
- * var gcloud = require('google-cloud')({
- *   keyFilename: '/path/to/keyfile.json',
- *   projectId: 'my-project'
- * });
- *
- * var bigtable = gcloud.bigtable({
- *   zone: 'us-central1-b',
- *   cluster: 'gcloud-node'
- * });
- *
  * //-
  * // <h3>Creating a Cluster</h3>
  * //

packages/bigtable/src/row.js

@@ -60,15 +60,6 @@ var RowError = createErrorClass('RowError', function(row) {
  * @alias module:bigtable/row
  *
  * @example
- * var gcloud = require('google-cloud');
- *
- * var bigtable = gcloud.bigtable({
- *   keyFilename: '/path/to/keyfile.json',
- *   projectId: 'grape-spaceship-123',
- *   cluster: 'gcloud-node',
- *   zone: 'us-central1-b'
- * });
- *
  * var table = bigtable.table('prezzy');
  * var row = table.row('gwashington');
  */

packages/bigtable/src/table.js

@@ -63,15 +63,6 @@ var Row = require('./row.js');
  * @param {string} name - Name of the table.
  *
  * @example
- * var gcloud = require('google-cloud');
- *
- * var bigtable = gcloud.bigtable({
- *   keyFilename: '/path/to/keyfile.json',
- *   projectId: 'grape-spaceship-123',
- *   cluster: 'gcloud-node',
- *   zone: 'us-central1-b'
- * });
- *
  * var table = bigtable.table('prezzy');
  */
 function Table(bigtable, name) {

packages/compute/src/address.js

@@ -39,13 +39,6 @@ var util = require('util');
  * @alias module:compute/address
  *
  * @example
- * var gcloud = require('google-cloud')({
- *   keyFilename: '/path/to/keyfile.json',
- *   projectId: 'grape-spaceship-123'
- * });
- *
- * var gce = gcloud.compute();
- *
  * var region = gce.region('region-name');
  *
  * var address = region.address('address1');

packages/compute/src/autoscaler.js

@@ -38,13 +38,6 @@ var util = require('util');
  * @alias module:compute/autoscaler
  *
  * @example
- * var gcloud = require('google-cloud')({
- *   keyFilename: '/path/to/keyfile.json',
- *   projectId: 'grape-spaceship-123'
- * });
- *
- * var gce = gcloud.compute();
- *
  * var zone = gce.zone('us-central1-a');
  *
  * var autoscaler = zone.autoscaler('autoscaler-name');

packages/compute/src/disk.js

@@ -47,13 +47,6 @@ var Snapshot = require('./snapshot.js');
  * @alias module:compute/disk
  *
  * @example
- * var gcloud = require('google-cloud')({
- *   keyFilename: '/path/to/keyfile.json',
- *   projectId: 'grape-spaceship-123'
- * });
- *
- * var gce = gcloud.compute();
- *
  * var zone = gce.zone('zone-name');
  *
  * var disk = zone.disk('disk1');

packages/compute/src/firewall.js

@@ -39,13 +39,6 @@ var util = require('util');
  * @alias module:compute/firewall
  *
  * @example
- * var gcloud = require('google-cloud')({
- *   keyFilename: '/path/to/keyfile.json',
- *   projectId: 'grape-spaceship-123'
- * });
- *
- * var gce = gcloud.compute();
- *
  * var firewall = gce.firewall('tcp-3000');
  */
 function Firewall(compute, name) {

packages/compute/src/health-check.js

@@ -47,13 +47,6 @@ var util = require('util');
  * @alias module:compute/health-check
  *
  * @example
- * var gcloud = require('google-cloud')({
- *   keyFilename: '/path/to/keyfile.json',
- *   projectId: 'grape-spaceship-123'
- * });
- *
- * var gce = gcloud.compute();
- *
  * var healthCheck = gce.healthCheck('health-check-name');
  */
 function HealthCheck(compute, name, options) {

packages/compute/src/index.js

@@ -83,31 +83,12 @@ var Zone = require('./zone.js');
 var PKG = require('../package.json');
 
 /**
- * A Compute object allows you to interact with the Google Compute Engine API.
- * Using this object, you can access your instances with {module:compute/vm},
- * disks with {module:compute/disk}, and firewalls with
- * {module:compute/firewall}.
- *
  * @alias module:compute
  * @constructor
  *
- * @classdesc
- * The object returned from `gcloud.compute` gives you complete control of your
- * Compute Engine virtual machines, disks, networks, snapshots, addresses,
- * firewalls, and more.
- *
- * To learn more about Compute Engine, see
- * [What is Google Compute Engine?](https://cloud.google.com/compute/docs)
+ * @resource [What is Google Compute Engine?]{@link https://cloud.google.com/compute/docs}
  *
  * @param {object} options - [Configuration object](#/docs).
- *
- * @example
- * var gcloud = require('google-cloud')({
- *   keyFilename: '/path/to/keyfile.json',
- *   projectId: 'grape-spaceship-123'
- * });
- *
- * var gce = gcloud.compute();
  */
 function Compute(options) {
   if (!(this instanceof Compute)) {

packages/compute/src/instance-group.js

@@ -43,13 +43,6 @@ var util = require('util');
  * @alias module:compute/instance-group
  *
  * @example
- * var gcloud = require('google-cloud')({
- *   keyFilename: '/path/to/keyfile.json',
- *   projectId: 'grape-spaceship-123'
- * });
- *
- * var gce = gcloud.compute();
- *
  * var zone = gce.zone('us-central1-a');
  *
  * var instanceGroup = zone.instanceGroup('web-servers');

packages/compute/src/machine-type.js

@@ -39,13 +39,6 @@ var util = require('util');
  * @alias module:compute/machine-type
  *
  * @example
- * var gcloud = require('google-cloud')({
- *   keyFilename: '/path/to/keyfile.json',
- *   projectId: 'grape-spaceship-123'
- * });
- *
- * var gce = gcloud.compute();
- *
  * var zone = gce.zone('us-central1-b');
  *
  * var machineType = zone.machineType('g1-small');

packages/compute/src/network.js

@@ -41,13 +41,6 @@ var util = require('util');
  * @alias module:compute/network
  *
  * @example
- * var gcloud = require('google-cloud')({
- *   keyFilename: '/path/to/keyfile.json',
- *   projectId: 'grape-spaceship-123'
- * });
- *
- * var gce = gcloud.compute();
- *
  * var network = gce.network('network-name');
  */
 function Network(compute, name) {

packages/compute/src/operation.js

@@ -44,13 +44,6 @@ var modelo = require('modelo');
  * @alias module:compute/operation
  *
  * @example
- * var gcloud = require('google-cloud')({
- *   keyFilename: '/path/to/keyfile.json',
- *   projectId: 'grape-spaceship-123'
- * });
- *
- * var gce = gcloud.compute();
- *
  * //-
  * // Reference a global operation.
  * //-

packages/compute/src/region.js

@@ -70,13 +70,6 @@ var Subnetwork = require('./subnetwork.js');
  * @alias module:compute/region
  *
  * @example
- * var gcloud = require('google-cloud')({
- *   keyFilename: '/path/to/keyfile.json',
- *   projectId: 'grape-spaceship-123'
- * });
- *
- * var gce = gcloud.compute();
- *
  * var region = gce.region('us-central1');
  */
 function Region(compute, name) {