Refactor and test Compute Engine

Author: stephenplusplus

README.md

@@ -15,6 +15,7 @@ This client supports the following Google Cloud Platform services:
 * [Google Cloud DNS](#google-cloud-dns)
 * [Google Cloud Pub/Sub](#google-cloud-pubsub)
 * [Google Cloud Storage](#google-cloud-storage)
+* [Google Compute Engine](#google-compute-engine)
 * [Google Cloud Search](#google-cloud-search-alpha) (Alpha)
 
 If you need support for other Google APIs, check out the [Google Node.js API Client library][googleapis].
@@ -300,6 +301,40 @@ localReadStream.pipe(remoteWriteStream);
 ```
 
 
+## Google Compute Engine
+
+- [API Documentation][gcloud-compute-docs]
+- [Official Documentation][cloud-compute-docs]
+
+#### Preview
+
+```js
+var gcloud = require('gcloud');
+
+// Authorizing on a per-API-basis. You don't need to do this if you auth on a
+// global basis (see Authorization section above).
+
+var gce = gcloud.compute({
+  projectId: 'my-project',
+  keyFilename: '/path/to/keyfile.json'
+});
+
+// Create a new VM using the latest OS image of your choice.
+var zone = gce.zone('us-central1-a');
+var name = 'ubuntu-http';
+
+zone.createVM(name, { os: 'ubuntu' }, function(err, vm, operation) {
+  // `operation` lets you check the status of long-running tasks.
+
+  operation.onComplete(function(err, metadata) {
+    if (!err) {
+      // Virtual machine created!
+    }
+  });
+});
+```
+
+
 ## Google Cloud Search (Alpha)
 
 > This is an *Alpha* release of Google Cloud Search. This feature is not covered by any SLA or deprecation policy and may be subject to backward-incompatible changes.
@@ -357,6 +392,7 @@ Apache 2.0 - See [COPYING](COPYING) for more information.
 [gcloud-homepage]: https://googlecloudplatform.github.io/gcloud-node/
 [gcloud-docs]: https://googlecloudplatform.github.io/gcloud-node/#/docs
 [gcloud-bigquery-docs]: https://googlecloudplatform.github.io/gcloud-node/#/docs/bigquery
+[gcloud-compute-docs]: https://googlecloudplatform.github.io/gcloud-node/#/docs/compute
 [gcloud-datastore-docs]: https://googlecloudplatform.github.io/gcloud-node/#/docs/datastore
 [gcloud-dns-docs]: https://googlecloudplatform.github.io/gcloud-node/#/docs/dns
 [gcloud-pubsub-docs]: https://googlecloudplatform.github.io/gcloud-node/#/docs/pubsub
@@ -376,6 +412,8 @@ Apache 2.0 - See [COPYING](COPYING) for more information.
 
 [cloud-bigquery-docs]: https://cloud.google.com/bigquery/what-is-bigquery
 
+[cloud-compute-docs]: https://cloud.google.com/compute/docs
+
 [cloud-datastore-docs]: https://cloud.google.com/datastore/docs
 [cloud-datastore-activation]: https://cloud.google.com/datastore/docs/activate
 

docs/json/master/compute/.gitkeep

@@ -0,0 +1,7 @@
+<h3>Compute Engine Overview</h3>
+<p>
+  The object returned from <code>gcloud.compute</code> gives you complete control of your Compute Engine virtual machines, disks, networks, snapshots, addresses, firewalls, and more.
+</p>
+<p>
+  To learn more about Compute Engine, see <a href="https://cloud.google.com/compute/docs">What is Google Compute Engine?</a>
+</p>

docs/site/components/docs/compute-overview.html

@@ -39,6 +39,49 @@ angular.module('gcloud.docs')
       ]
     },
 
+    compute: {
+      title: 'Compute',
+      _url: '{baseUrl}/compute',
+      pages: [
+        {
+          title: 'Address',
+          url: '/address'
+        },
+        {
+          title: 'Disk',
+          url: '/disk'
+        },
+        {
+          title: 'Firewall',
+          url: '/firewall'
+        },
+        {
+          title: 'Network',
+          url: '/network'
+        },
+        {
+          title: 'Operation',
+          url: '/operation'
+        },
+        {
+          title: 'Region',
+          url: '/region'
+        },
+        {
+          title: 'Snapshot',
+          url: '/snapshot'
+        },
+        {
+          title: 'VM',
+          url: '/vm'
+        },
+        {
+          title: 'Zone',
+          url: '/zone'
+        }
+      ]
+    },
+
     datastore: {
       title: 'Datastore',
       _url: '{baseUrl}/datastore',
@@ -180,6 +223,9 @@ angular.module('gcloud.docs')
       '>=0.16.0': ['search'],
 
       // introduce dns api.
-      '>=0.18.0': ['dns']
+      '>=0.18.0': ['dns'],
+
+      // introduce compute api.
+      '>=0.20.0': ['compute']
     }
   });

docs/site/components/docs/docs-values.js

@@ -44,7 +44,7 @@ <h3 class="sub-heading">
     </article>
     <hr>
 
-    <article ng-repeat="service in ['bigquery', 'datastore', 'dns', 'pubsub', 'search', 'storage']"
+    <article ng-repeat="service in ['bigquery', 'compute', 'datastore', 'dns', 'pubsub', 'search', 'storage']"
              ng-if="isActiveDoc(service)"
              ng-include="'site/components/docs/' + service + '-overview.html'">
     </article>

docs/site/components/docs/docs.html

@@ -1,5 +1,5 @@
 /*!
- * Copyright 2014 Google Inc. All Rights Reserved.
+ * Copyright 2015 Google Inc. All Rights Reserved.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -26,85 +26,101 @@
  */
 var util = require('../common/util.js');
 
-/**
- * Create an Address object to interact with a Google Compute Engine address.
+/*! Developer Documentation
  *
- * @constructor
- * @alias module:region/address
+ * @param {module:region} region - Region this address belongs to.
+ * @param {string} name - The name of the address.
+ */
+/**
+ * An Address object allows you to interact with a Google Compute Engine
+ * address.
  *
- * @throws {Error} if an address name or a region are not provided.
+ * @resource [Instances and Networks]{@link https://cloud.google.com/compute/docs/instances-and-network}
+ * @resource [Address Resource]{@link https://cloud.google.com/compute/docs/reference/v1/addresses} *
  *
- * @param {module:region} region - The Google Compute Engine region this
- *     address belongs to.
- * @param {string} name - The name of the address.
- * @param {object=} metadata - Address metadata.
+ * @constructor
+ * @alias module:compute/address
  *
  * @example
  * var gcloud = require('gcloud')({
- *   keyFilename: '/path/to/keyfile.json'
+ *   keyFilename: '/path/to/keyfile.json',
+ *   projectId: 'grape-spaceship-123'
  * });
  *
- * var compute = gcloud.compute();
+ * var gce = gcloud.compute();
  *
- * var myRegion = compute.region('region-name');
+ * var region = gce.region('region-name');
  *
- * var address = myRegion.address('address1');
+ * var address = region.address('address1');
  */
-function Address(region, name, metadata) {
+function Address(region, name) {
   this.region = region;
   this.name = name;
-  this.metadata = metadata;
-
-  if (!util.is(this.name, 'string')) {
-    throw new Error('A name is needed to use a Compute Engine Address.');
-  }
-  if (!this.region) {
-    throw new Error('A region is needed to use a Compute Engine Address.');
-  }
+  this.metadata = {};
 }
 
 /**
  * Delete the address.
  *
- * @param {function} callback - The callback function.
+ * @resource [Addresses: delete API Documentation]{@link https://cloud.google.com/compute/docs/reference/v1/addresses/delete}
+ *
+ * @param {function=} callback - The callback function.
+ * @param {?error} callback.err - An error returned while making this request.
+ * @param {module:compute/operation} callback.operation - An operation object
+ *     that can be used to check the status of the request.
+ * @param {object} callback.apiResponse - The full API response.
  *
  * @example
- * address.delete(function(err, operation) {
- *   // `operation` is an Operation object and can be used to check the status
- *   // of address deletion.
+ * address.delete(function(err, operation, apiResponse) {
+ *   // `operation` is an Operation object that can be used to check the status
+ *   // of the request.
  * });
  */
 Address.prototype.delete = function(callback) {
   callback = callback || util.noop;
+
   var region = this.region;
-  this.makeReq_('DELETE', '', null, true, function(err, resp) {
+
+  this.makeReq_('DELETE', '', null, null, function(err, resp) {
     if (err) {
-      callback(err);
+      callback(err, null, resp);
       return;
     }
+
     var operation = region.operation(resp.name);
     operation.metadata = resp;
-    callback(null, operation);
+
+    callback(null, operation, resp);
   });
 };
 
 /**
- * Get the address' metadata.
+ * Get the metadata of this address.
+ *
+ * @resource [Address Resource]{@link https://cloud.google.com/compute/docs/reference/v1/addresses}
+ * @resource [Addresses: get API Documentation]{@link https://cloud.google.com/compute/docs/reference/v1/addresses/get}
  *
  * @param {function=} callback - The callback function.
+ * @param {?error} callback.err - An error returned while making this request
+ * @param {object} callback.metadata - The address's metadata.
+ * @param {object} callback.apiResponse - The full API response.
  *
  * @example
  * address.getMetadata(function(err, metadata, apiResponse) {});
  */
 Address.prototype.getMetadata = function(callback) {
   callback = callback || util.noop;
+
   var self = this;
+
   this.makeReq_('GET', '', null, null, function(err, resp) {
     if (err) {
-      callback(err);
+      callback(err, null, resp);
       return;
     }
+
     self.metadata = resp;
+
     callback(null, self.metadata, resp);
   });
 };
@@ -126,4 +142,4 @@ Address.prototype.makeReq_ = function(method, path, query, body, callback) {
   this.region.makeReq_(method, path, query, body, callback);
 };
 
-module.exports = Address;
+module.exports = Address;