docs: refine examples & add missing DNS overview

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

@@ -0,0 +1,7 @@
+<h3>DNS Overview</h3>
+<p>
+  The object returned from <code>gcloud.dns</code> gives you complete control over your managed zones.
+</p>
+<p>
+  To learn more about Google Cloud DNS, see <a href="https://cloud.google.com/dns/what-is-cloud-dns">What is Google Cloud DNS?</a>
+</p>

docs/site/components/docs/docs.html

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

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

@@ -1,6 +1,6 @@
 <h3>Pub/Sub Overview</h3>
 <p class="notice">
-  Google Cloud Pub/Sub is in Alpha status. As a result, it might be changed in backward-incompatible ways and is not recommended for production use. It is not subject to any SLA or deprecation policy.
+  <strong>This is a Beta release of Google Cloud Pub/Sub.</strong> This feature is not covered by any SLA or deprecation policy and may be subject to backward-incompatible changes.
 </p>
 <p>
   The <code>gcloud.pubsub</code> method will return a <code>pubsub</code> object, allowing you to create topics, publish messages, subscribe to topics, and more.

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

@@ -1,4 +1,7 @@
 <h3>Search Overview</h3>
+<p class="notice">
+  <strong>This is an Alpha release of Google Cloud Search.</strong> This feature is not covered by any SLA or deprecation policy and may be subject to backward-incompatible changes.
+</p>
 <p>
   The object returned from <code>gcloud.search</code> gives you complete access to store your documents and search your indexes.
 </p>

lib/dns/index.js

@@ -57,9 +57,11 @@ var SCOPES = [
 ];
 
 /**
- * [Google Cloud DNS](https://cloud.google.com/dns) is a reliable, resilient,
- * low-latency DNS serving from Google’s worldwide network of Anycast DNS
- * servers.
+ * [Google Cloud DNS](https://cloud.google.com/dns/what-is-cloud-dns) is a high-
+ * performance, resilient, global DNS service that provides a cost-effective way
+ * to make your applications and services available to your users. This
+ * programmable, authoritative DNS service can be used to easily publish and
+ * manage DNS records using the same infrastructure relied upon by Google.
  *
  * @constructor
  * @alias module:dns

lib/index.js

@@ -96,30 +96,30 @@ var util = require('./common/util.js');
  *
  * @example
  * var gcloud = require('gcloud')({
- *   keyFilename: '/path/to/keyfile.json',
- *   projectId: 'my-project'
+ *   projectId: 'grape-spaceship-123',
+ *   keyFilename: '/path/to/keyfile.json'
  * });
  *
- * var dataset = gcloud.datastore.dataset();
- * // equal to:
- * //   gcloud.datastore.dataset({
- * //     keyFilename: '/path/to/keyfile.json',
- * //     projectId: 'my-project'
- * //   });
- *
+ * //-
+ * // From the same authentication credentials, you may now access your Google
+ * // Cloud Storage buckets, for example.
+ * //-
  * var gcs = gcloud.storage();
- * var bucket = gcs.bucket({
- *   name: 'PhotosBucket',
- *   // properties may be overridden:
+ * var bucket = gcs.bucket('photos');
+ *
+ * //-
+ * // However, if you need to override the global credentials, you may provide
+ * // new ones.
+ * //-
+ * var otherGcs = gcloud.storage({
  *   keyFilename: '/path/to/other/keyfile.json'
  * });
+ * var otherBucket = otherGcs.bucket('other-photos');
  *
- * @example
- * var gcloud = require('gcloud')({
- *   keyFilename: '/path/to/keyfile.json',
- *   projectId: 'my-project',
- *   maxRetries: 5 // retry rate limited requests 5 times before giving up
- * });
+ * //-
+ * // `gcs` and `otherGcs` will use their respective credentials for all future
+ * // API requests.
+ * //-
  */
 function gcloud(config) {
   return {
@@ -160,7 +160,7 @@ function gcloud(config) {
  * @example
  * var gcloud = require('gcloud');
  * var bigquery = gcloud.bigquery({
- *   projectId: 'project-id',
+ *   projectId: 'grape-spaceship-123',
  *   keyFilename: '/path/to/keyfile.json'
  * });
  */
@@ -180,24 +180,42 @@ gcloud.bigquery = BigQuery;
  * var gcloud = require('gcloud');
  * var datastore = gcloud.datastore;
  * var dataset = datastore.dataset({
- *   projectId: 'project-id',
+ *   projectId: 'grape-spaceship-123',
  *   keyFilename: '/path/to/keyfile.json'
  * });
  */
 gcloud.datastore = Datastore;
 
+/**
+ * [Google Cloud DNS](https://cloud.google.com/dns/what-is-cloud-dns) is a high-
+ * performance, resilient, global DNS service that provides a cost-effective way
+ * to make your applications and services available to your users. This
+ * programmable, authoritative DNS service can be used to easily publish and
+ * manage DNS records using the same infrastructure relied upon by Google.
+ *
+ * @type {module:dns}
+ *
+ * @return {module:dns}
+ *
+ * @example
+ * var gcloud = require('gcloud');
+ * var dns = gcloud.dns({
+ *   projectId: 'grape-spaceship-123',
+ *   keyFilename: '/path/to/keyfile.json'
+ * });
+ */
 gcloud.dns = DNS;
 
 /**
- * **Experimental**
- *
  * [Google Cloud Pub/Sub](https://developers.google.com/pubsub/overview) is a
  * reliable, many-to-many, asynchronous messaging service from Google Cloud
  * Platform.
  *
- * Note: This is a *Beta* release of Google Cloud Pub/Sub. This feature is not
- * covered by any SLA or deprecation policy and may be subject to backward-
- * incompatible changes.
+ * <p class="notice">
+ *   **This is a Beta release of Google Cloud Pub/Sub.** This feature is not
+ *   covered by any SLA or deprecation policy and may be subject to backward-
+ *   incompatible changes.
+ * </p>
  *
  * @type {module:pubsub}
  *
@@ -206,25 +224,23 @@ gcloud.dns = DNS;
  * @example
  * var gcloud = require('gcloud');
  * var pubsub = gcloud.pubsub({
- *   projectId: 'project-id',
+ *   projectId: 'grape-spaceship-123',
  *   keyFilename: '/path/to/keyfile.json'
  * });
  */
-gcloud.pubsub = function(config) {
-  return new PubSub(config);
-};
+gcloud.pubsub = PubSub;
 
 /**
- * **Experimental**
- *
  * [Google Cloud Search](https://cloud.google.com/search/) allows you to quickly
  * perform full-text and geospatial searches against your data without having to
  * spin up your own instances and without the hassle of managing and maintaining
  * a search service.
  *
- * Note: 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.
+ * <p class="notice">
+ *   **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.
+ * </p>
  *
  * @type {module:search}
  *
@@ -233,13 +249,11 @@ gcloud.pubsub = function(config) {
  * @example
  * var gcloud = require('gcloud');
  * var search = gcloud.search({
- *   projectId: 'project-id',
+ *   projectId: 'grape-spaceship-123',
  *   keyFilename: '/path/to/keyfile.json'
  * });
  */
-gcloud.search = function(config) {
-  return new Search(config);
-};
+gcloud.search = Search;
 
 /**
  * Google Cloud Storage allows you to store data on Google infrastructure.
@@ -253,7 +267,7 @@ gcloud.search = function(config) {
  * @example
  * var gcloud = require('gcloud');
  * var gcs = gcloud.storage({
- *   projectId: 'project-id',
+ *   projectId: 'grape-spaceship-123',
  *   keyFilename: '/path/to/keyfile.json'
  * });
  */

lib/pubsub/index.js

@@ -87,6 +87,10 @@ var SCOPES = [
  * var pubsub = gcloud.pubsub();
  */
 function PubSub(options) {
+  if (!(this instanceof PubSub)) {
+    return new PubSub(options);
+  }
+
   options = options || {};
 
   if (!options.projectId) {

lib/search/index.js

@@ -80,7 +80,13 @@ var SEARCH_BASE_URL = 'https://cloudsearch.googleapis.com/v1/';
  * var search = gcloud.search();
  */
 function Search(options) {
-  if (!options || !options.projectId) {
+  if (!(this instanceof Search)) {
+    return new Search(options);
+  }
+
+  options = options || {};
+
+  if (!options.projectId) {
     throw util.missingProjectIdError;
   }