docs: upstream links

.jscsrc

@@ -14,5 +14,9 @@
     "try",
     "typeof"
   ],
-  "requireCamelCaseOrUpperCaseIdentifiers": "ignoreProperties"
+  "requireCamelCaseOrUpperCaseIdentifiers": "ignoreProperties",
+  "maximumLineLength": {
+    "value": 80,
+    "allowUrlComments": true
+  }
 }

.jshintrc

@@ -7,7 +7,6 @@
   "immed": true,
   "indent": 2,
   "latedef": "nofunc",
-  "maxlen": 80,
   "newcap": true,
   "node": true,
   "noarg": true,

docs/site/components/docs/docs-directives.js

@@ -26,7 +26,7 @@ angular.module('gcloud.docs')
     }
 
     return {
-      template: '<a href="{{link}}">(code on GitHub)</a>',
+      template: '<a href="{{link}}">Source Code</a>',
 
       link: function($scope) {
         var method = $scope.method;

docs/site/components/docs/docs.html

@@ -54,7 +54,6 @@ <h3 class="sub-heading">
       ng-hide="singleMethod && method.name !== singleMethod">
       <h2 ng-if="method.name[0].toUpperCase() === method.name[0]">
         {{method.name}}
-        <span class="view-code-link" docs-code-link></span>
       </h2>
       <h3
         class="method-heading"
@@ -65,7 +64,6 @@ <h2 ng-if="method.name[0].toUpperCase() === method.name[0]">
           <span>#</span>
           {{method.name}}
         </a>
-        <span class="view-code-link" docs-code-link></span>
       </h3>
       <p ng-if="method.description" ng-bind-html="method.description"></p>
       <div ng-show="method.name[0].toUpperCase() === method.name[0]"
@@ -104,6 +102,11 @@ <h4 ng-show="method.returns">Returns</h4>
       <h4 ng-show="method.example">Example</h4>
       <div docs-example ng-repeat-end
         ng-show="method.example" ng-bind-html="method.example"></div>
+      <h4>More information</h4>
+      <ul class="resource-links">
+        <li docs-code-link></li>
+        <li ng-repeat="doc in method.docs" ng-bind-html="doc"></li>
+      </ul>
       <hr ng-if="$index < methods.length - 1">
     </article>
   </article>

docs/site/components/docs/docs.js

@@ -184,7 +184,13 @@ angular
                 })
                 .map(function(tag) {
                   return $sce.trustAsHtml(formatComments(tag.string));
-                })[0]
+                })[0],
+              docs: obj.tags.filter(function(tag) {
+                  return tag.type === 'resource'
+                })
+                .map(function(tag) {
+                  return $sce.trustAsHtml(formatHtml(detectLinks(tag.string)));
+                })
             };
           })
           .sort(compareMethods);

docs/site/css/main.css

@@ -933,6 +933,12 @@ ul {
   color: #888;
 }
 
+.resource-links {
+  margin: 0;
+  padding: 8px;
+  background-color: #f5f8ff;
+}
+
 /*
  Page Title
 */

lib/bigquery/dataset.js

@@ -56,6 +56,8 @@ function Dataset(bigQuery, id) {
 /**
  * Create a table given a tableId or configuration object.
  *
+ * @resource [Tables: insert API Documentation]{@link https://cloud.google.com/bigquery/docs/reference/v2/tables/insert}
+ *
  * @param {object} options - Table id or configuration object.
  * @param {string} options.id - The id of the table.
  * @param {string|object} options.schema - A comma-separated list of name:type
@@ -117,6 +119,8 @@ Dataset.prototype.createTable = function(options, callback) {
 /**
  * Delete the dataset.
  *
+ * @resource [Datasets: delete API Documentation]{@link https://cloud.google.com/bigquery/docs/reference/v2/datasets/delete}
+ *
  * @param {object=} options - The configuration object.
  * @param {boolean} options.force - Force delete dataset and all tables.
  *     Default: false.
@@ -151,6 +155,8 @@ Dataset.prototype.delete = function(options, callback) {
 /**
  * Get the metadata for the Dataset.
  *
+ * @resource [Datasets: get API Documentation]{@link https://cloud.google.com/bigquery/docs/reference/v2/datasets/get}
+ *
  * @param {function} callback - The callback function.
  * @param {?error} callback.err - An error returned while making this request
  * @param {object} callback.metadata - The Dataset metadata
@@ -176,6 +182,8 @@ Dataset.prototype.getMetadata = function(callback) {
 /**
  * Get a list of tables.
  *
+ * @resource [Tables: list API Documentation]{@link https://cloud.google.com/bigquery/docs/reference/v2/tables/list}
+ *
  * @param {object=} query - Configuration object.
  * @param {number} query.maxResults - Maximum number of results to return.
  * @param {string} query.pageToken - Token returned from a previous call, to
@@ -271,6 +279,8 @@ Dataset.prototype.query = function(options, callback) {
 /**
  * Sets the metadata of the Dataset object.
  *
+ * @resource [Datasets: patch API Documentation]{@link https://cloud.google.com/bigquery/docs/reference/v2/datasets/patch}
+ *
  * @param {object} metadata - Metadata to save on the Dataset.
  * @param {function} callback - The callback function.
  * @param {?error} callback.err - An error returned while making this request

lib/bigquery/index.js

@@ -118,6 +118,8 @@ function BigQuery(options) {
 /**
  * Create a dataset.
  *
+ * @resource [Datasets: insert API Documentation]{@link https://cloud.google.com/bigquery/docs/reference/v2/datasets/insert}
+ *
  * @param {string} id - ID of the dataset to create.
  * @param {function} callback  - The callback function.
  * @param {?error} callback.err - An error returned while making this request
@@ -165,6 +167,8 @@ BigQuery.prototype.dataset = function(id) {
 /**
  * List all or some of the datasets in your project.
  *
+ * @resource [Datasets: list API Documentation]{@link https://cloud.google.com/bigquery/docs/reference/v2/datasets/list}
+ *
  * @param {object=} query - Configuration object.
  * @param {boolean} query.all - List all datasets, including hidden ones.
  * @param {boolean} query.autoPaginate - Have pagination handled automatically.
@@ -260,6 +264,8 @@ BigQuery.prototype.getDatasets = function(query, callback) {
 /**
  * Get all of the jobs from your project.
  *
+ * @resource [Jobs: list API Documentation]{@link https://cloud.google.com/bigquery/docs/reference/v2/jobs/list}
+ *
  * @param {object=} options - Configuration object.
  * @param {boolean=} options.allUsers - Display jobs owned by all users in the
  *     project.
@@ -385,6 +391,8 @@ BigQuery.prototype.job = function(id) {
  * In cases where more results exist, this will automatically run the subsequent
  * queries for you, pushing each row to the stream.
  *
+ * @resource [Jobs: query API Documentation]{@link https://cloud.google.com/bigquery/docs/reference/v2/jobs/query}
+ *
  * @param {string|object} options - A string SQL query or configuration object.
  * @param {boolean} options.autoPaginate - Have pagination handled
  *     automatically. Default: true.
@@ -500,6 +508,8 @@ BigQuery.prototype.query = function(options, callback) {
  * ping for the results. See the Job documentation for explanations of how to
  * check on the status of the job.
  *
+ * @resource [Jobs: insert API Documentation]{@link https://cloud.google.com/bigquery/docs/reference/v2/jobs/insert}
+ *
  * @param {object|string} options - The configuration object. This must be in
  *     the format of the [`configuration.query`](http://goo.gl/wRpHvR) property
  *     of a Jobs resource. If a string is provided, this is used as the query

lib/bigquery/job.js

@@ -60,6 +60,8 @@ function Job(bigQuery, id) {
  * Get the metadata of the job. This will mostly be useful for checking the
  * status of a previously-run job.
  *
+ * @resource [Jobs: get API Documentation]{@link https://cloud.google.com/bigquery/docs/reference/v2/jobs/get}
+ *
  * @param {function} callback - The callback function.
  * @param {?error} callback.err - An error returned while making this request
  * @param {object} callback.metadata - The metadata of the job.
@@ -89,6 +91,8 @@ Job.prototype.getMetadata = function(callback) {
 /**
  * Get the results of a job.
  *
+ * @resource [Jobs: getQueryResults API Documentation]{@link https://cloud.google.com/bigquery/docs/reference/v2/jobs/getQueryResults}
+ *
  * @param {object=} options - Configuration object.
  * @param {boolean} options.autoPaginate - Have pagination handled
  *     automatically. Default: true.

lib/bigquery/table.js

@@ -133,6 +133,8 @@ Table.mergeSchemaWithRows_ = function(schema, rows) {
 /**
  * Copy data from one table to another, optionally creating that table.
  *
+ * @resource [Jobs: insert API Documentation]{@link https://cloud.google.com/bigquery/docs/reference/v2/jobs/insert}
+ *
  * @param {module:bigquery/table} destination - The destination table.
  * @param {object=} metadata - Metadata to set with the copy operation. The
  *     metadata object should be in the format of the
@@ -205,6 +207,8 @@ Table.prototype.copy = function(destination, metadata, callback) {
  * Create a readable stream of the rows of data in your table. This method is
  * simply a wrapper around {module:bigquery/table#getRows}.
  *
+ * @resource [Tabledata: list API Documentation]{@link https://cloud.google.com/bigquery/docs/reference/v2/tabledata/list}
+ *
  * @return {ReadStream}
  *
  * @example
@@ -225,6 +229,8 @@ Table.prototype.createReadStream = function() {
  * Load data into your table from a readable stream of JSON or CSV-formatted
  * data.
  *
+ * @resource [Jobs: insert API Documentation]{@link https://cloud.google.com/bigquery/docs/reference/v2/jobs/insert}
+ *
  * @param {string|object=} metadata - Metadata to set with the load operation.
  *     The metadata object should be in the format of the
  *     [`configuration.load`](http://goo.gl/BVcXk4) property of a Jobs resource.
@@ -332,6 +338,8 @@ Table.prototype.createWriteStream = function(metadata) {
 /**
  * Delete a table and all its data.
  *
+ * @resource [Tables: delete API Documentation]{@link https://cloud.google.com/bigquery/docs/reference/v2/tables/delete}
+ *
  * @param {function} callback - The callback function.
  * @param {?error} callback.err - An error returned while making this request
  * @param {object} callback.apiResponse - The full API response.
@@ -346,6 +354,8 @@ Table.prototype.delete = function(callback) {
 /**
  * Export table to Google Cloud Storage.
  *
+ * @resource [Jobs: insert API Documentation]{@link https://cloud.google.com/bigquery/docs/reference/v2/jobs/insert}
+ *
  * @param {module:storage/file} destination - Where the file should be exported
  *     to.
  * @param {object=} options - The configuration object.
@@ -469,6 +479,8 @@ Table.prototype.export = function(destination, options, callback) {
 /**
  * Return the metadata associated with the Table.
  *
+ * @resource [Tables: get API Documentation]{@link https://cloud.google.com/bigquery/docs/reference/v2/tables/get}
+ *
  * @param {function} callback - The callback function.
  * @param {?error} callback.err - An error returned while making this request
  * @param {object} callback.metadata - The metadata of the Table.
@@ -496,6 +508,8 @@ Table.prototype.getMetadata = function(callback) {
  * Retrieves table data from a specified set of rows. The rows are returned to
  * your callback as an array of objects matching your table's schema.
  *
+ * @resource [Tabledata: list API Documentation]{@link https://cloud.google.com/bigquery/docs/reference/v2/tabledata/list}
+ *
  * @param {object=} options - The configuration object.
  * @param {boolean} options.autoPaginate - Have pagination handled
  *     automatically. Default: true.
@@ -612,6 +626,8 @@ Table.prototype.getRows = function(options, callback) {
  * inferred by the given file's extension. If you wish to override this, you
  * must provide a `metadata` object.
  *
+ * @resource [Jobs: insert API Documentation]{@link https://cloud.google.com/bigquery/docs/reference/v2/jobs/insert}
+ *
  * @param {string|module:storage/file} source - The source file to import.
  * @param {object=} metadata - Metadata to set with the load operation. The
  *     metadata object should be in the format of the
@@ -740,6 +756,8 @@ Table.prototype.import = function(source, metadata, callback) {
  * recommended that you load data into BigQuery using
  * {module:bigquery/table#import} instead.
  *
+ * @resource [Tabledata: insertAll API Documentation]{@link https://cloud.google.com/bigquery/docs/reference/v2/tabledata/insertAll}
+ *
  * @param {object|object[]} rows - The rows to insert into the table.
  * @param {function} callback - The callback function.
  * @param {?error} callback.err - An error returned while making this request.
@@ -836,6 +854,8 @@ Table.prototype.query = function(query, callback) {
 /**
  * Set the metadata on the table.
  *
+ * @resource [Tables: update API Documentation]{@link https://cloud.google.com/bigquery/docs/reference/v2/tables/update}
+ *
  * @param {object} metadata - The metadata key/value object to set.
  * @param {string} metadata.description - A user-friendly description of the
  *     table.

lib/datastore/dataset.js

@@ -196,7 +196,7 @@ Dataset.prototype.key = function(options) {
  * Create a query from the current dataset to query the specified kind, scoped
  * to the namespace provided at the initialization of the dataset.
  *
- * *[Reference](http://goo.gl/Cag0r6).*
+ * @resource [Datastore Queries]{@link http://goo.gl/Cag0r6}
  *
  * @borrows {module:datastore/query} as createQuery
  * @see {module:datastore/query}
@@ -221,6 +221,8 @@ Dataset.prototype.createQuery = function(namespace, kind) {
  * provided in the callback function to commit your changes. See an example
  * below for more information.
  *
+ * @resource [Datasets: beginTransaction API Documentation]{@link https://cloud.google.com/datastore/docs/apis/v1beta2/datasets/beginTransaction}
+ *
  * @borrows {module:datastore/transaction#begin} as runInTransaction
  *
  * @param {function} fn - The function to run in the context of a transaction.

lib/datastore/query.js

@@ -30,7 +30,7 @@ var extend = require('extend');
  * {@linkcode module:datastore/dataset#createQuery} and run via
  * {@linkcode module:datastore/dataset#runQuery}.**
  *
- * *[More information on queries](http://goo.gl/Cag0r6).*
+ * @resource [Datastore Queries]{@link http://goo.gl/Cag0r6}
  *
  * @constructor
  * @alias module:datastore/query
@@ -91,7 +91,7 @@ Query.prototype.autoPaginate = function(autoPaginateVal) {
  *
  * *To filter by ancestors, see {@linkcode module:datastore/query#hasAncestor}.*
  *
- * *[More information on filtering by properties](http://goo.gl/ENCx7e).*
+ * @resource [Datastore Filters]{@link https://cloud.google.com/datastore/docs/concepts/queries#Datastore_Filters}
  *
  * @param {string} filter - Property + Operator (=, <, >, <=, >=).
  * @param {*} value - Value to compare property to.
@@ -126,7 +126,7 @@ Query.prototype.filter = function(filter, value) {
 /**
  * Filter a query by ancestors.
  *
- * *[More information on filtering by ancestors](http://goo.gl/1qfpkZ).*
+ * @resource [Datastore Ancestor Filters]{@link https://cloud.google.com/datastore/docs/concepts/queries#Datastore_Ancestor_filters}
  *
  * @param {Key} key - Key object to filter by.
  * @return {module:datastore/query}
@@ -144,7 +144,7 @@ Query.prototype.hasAncestor = function(key) {
  * Sort the results by a property name in ascending or descending order. By
  * default, an ascending sort order will be used.
  *
- * *[More information on sort orders](http://goo.gl/mfegFR).*
+ * @resource [Datastore Sort Orders]{@link https://cloud.google.com/datastore/docs/concepts/queries#Datastore_Sort_orders}
  *
  * @param {string} property - Optional operator (+, -) and property to order by.
  * @return {module:datastore/query}
@@ -188,7 +188,7 @@ Query.prototype.groupBy = function(fieldNames) {
  *
  * Queries that select a subset of properties are called Projection Queries.
  *
- * *[More information on projection queries](http://goo.gl/EfsrJl).*
+ * @resource [Projection Queries]{@link https://cloud.google.com/datastore/docs/concepts/projectionqueries}
  *
  * @param {string|string[]} fieldNames - Properties to return from the matched
  *     entities.
@@ -210,7 +210,7 @@ Query.prototype.select = function(fieldNames) {
 /**
  * Set a starting cursor to a query.
  *
- * *[More information on query cursors](http://goo.gl/WuTGRI).*
+ * @resource [Query Cursors]{@link https://cloud.google.com/datastore/docs/concepts/queries#Datastore_Query_cursors}
  *
  * @param {string} cursorToken - The starting cursor token.
  * @return {module:datastore/query}
@@ -230,7 +230,7 @@ Query.prototype.start = function(start) {
 /**
  * Set an ending cursor to a query.
  *
- * *[More information on query cursors](http://goo.gl/WuTGRI).*
+ * @resource [Query Cursors]{@link https://cloud.google.com/datastore/docs/concepts/queries#Datastore_Query_cursors}
  *
  * @param {string} cursorToken - The ending cursor token.
  * @return {module:datastore/query}
@@ -250,7 +250,7 @@ Query.prototype.end = function(end) {
 /**
  * Set a limit on a query.
  *
- * *[More information on query limits](http://goo.gl/f0VZ0n).*
+ * @resource [Query Limits]{@link https://cloud.google.com/datastore/docs/concepts/queries#Datastore_Retrieving_results}
  *
  * @param {number} n - The number of results to limit the query to.
  * @return {module:datastore/query}
@@ -268,7 +268,7 @@ Query.prototype.limit = function(n) {
 /**
  * Set an offset on a query.
  *
- * *[More information on query offsets](http://goo.gl/f0VZ0n).*
+ * @resource [Query Offsets]{@link https://cloud.google.com/datastore/docs/concepts/queries#Datastore_Retrieving_results}
  *
  * @param {number} n - The offset to start from after the start cursor.
  * @return {module:datastore/query}