All Storage samples are now up to standard. (#182)

* All Storage samples are now up to standard. * Address comments * Address comments * Remove .only * Fixed links

Author: jmdobry

CONTRIBUTING.md

@@ -27,6 +27,65 @@ accept your pull requests.
 1. Fork the desired repo, develop and test your code changes.
 1. Ensure that your code adheres to the existing style in the sample to which you are contributing. Refer to the
  [Google Cloud Platform Samples Style Guide](https://github.com/GoogleCloudPlatform/Template/wiki/style.html) for the
- recommended coding standards for this organization. You can run `npm run jshint` to match our JavaScript coding standards. 
+ recommended coding standards for this organization. You can run `npm run jshint` to match our JavaScript coding standards.
 1. Ensure that your code has an appropriate set of unit tests which all pass.
 1. Submit a pull request!
+
+## Sample template
+
+```
+<LICENSE_HEADER>
+
+// [START all]
+// [START setup]
+// By default, the client will authenticate using the service account file
+// specified by the GOOGLE_APPLICATION_CREDENTIALS environment variable and use
+// the project specified by the GCLOUD_PROJECT environment variable. See
+// https://googlecloudplatform.github.io/gcloud-node/#/docs/google-cloud/latest/guides/authentication
+var <API_CLIENT> = require('@google-cloud/<API>');
+
+// Instantiate a <API> client
+var <CLIENT> = <API_CLIENT>();
+// [END setup]
+
+// [START <REGION_TAG_NAME>]
+/**
+ * <DESCRIPTION>
+ *
+ * @param {<TYPE>} <NAME> <DESCRIPTION>.
+ * @param {function} cb The callback function.
+ */
+function <METHOD_NAME> (<ARGUMENTS>, callback) {
+ // <SETUP>
+
+ // <RUN SAMPLE CODE>
+
+ // Inside callback: console.log(<MESSAGE>)
+}
+// [END <REGION_TAG_NAME>]
+
+// The command-line program
+var cli = require('yargs');
+
+var program = module.exports = {
+ <METHOD_NAME>: <METHOD_NAME>,
+ main: function (args) {
+ // Run the command-line program
+ cli.help().strict().parse(args).argv;
+ }
+};
+
+cli
+ .demand(1)
+ .command('<COMMAND> <ARGS>', '<DESCRIPTION>.', {}, function (options) {
+ program.<METHOD_NAME>(options, console.log);
+ })
+ .example('node $0 <COMMAND> <ARGS>', '<DESCRIPTION>.')
+ .wrap(100)
+ .recommendCommands()
+ .epilogue('For more information, see <DOCS_LINK>');
+
+if (module === require.main) {
+ program.main(process.argv.slice(2));
+}
+```

storage/README.md

@@ -42,11 +42,12 @@ Commands:
  delete <entity> Delete access controls from a bucket or file.
 
 Options:
- --bucket, -b The target storage bucket. [string] [required]
- --default, -d Whether to set default access controls. Only valid when setting access controls on
- a bucket. [boolean]
- --file, -f The target file. [string]
- --help Show help [boolean]
+ --bucket, -b The target storage bucket. [string] [required]
+ --default, -d Whether to set default access
+ controls. Only valid when setting
+ access controls on a bucket. [boolean]
+ --file, -f The target file. [string]
+ --help Show help [boolean]
 
 Examples:
  node acl add user-bob@domain.com OWNER -b mybucket Add OWNER access controls for
@@ -71,19 +72,20 @@ View the [documentation][buckets_docs] or the [source code][buckets_code].
 __Usage:__ `node buckets --help`
 
 ```
-Usage: node buckets COMMAND [ARGS...]
-
 Commands:
+ create <bucket> Create a new bucket with the given name.
+ list List all buckets in the authenticated project.
+ delete <bucket> Delete the specified bucket.
 
- create BUCKET_NAME
- list
- delete BUCKET_NAME
+Options:
+ --help Show help [boolean]
 
 Examples:
+ node buckets create my-bucket Create a new bucket named "my-bucket".
+ node buckets list List all buckets in the authenticated project.
+ node buckets delete my-bucket Delete "my-bucket".
 
- node buckets create my-bucket
- node buckets list
- node buckets delete my-bucket
+For more information, see https://cloud.google.com/storage/docs
 ```
 
 [buckets_docs]: https://cloud.google.com/storage/docs
@@ -96,21 +98,25 @@ View the [documentation][encryption_docs] or the [source code][encryption_code].
 __Usage:__ `node encryption --help`
 
 ```
-Usage: node encryption COMMAND [ARGS...]
-
 Commands:
+ generate-encryption-key Generate a sample encryption key.
+ upload <bucket> <srcFile> <destFile> <key> Upload an encrypted file to a bucket.
+ download <bucket> <srcFile> <destFile> <key> Download an encrypted file from a bucket.
+ rotate <bucket> <file> <oldkey> <newKey> Rotate encryption keys for a file.
 
- generate-encryption-key
- upload BUCKET_NAME SRC_FILE_NAME DEST_FILE_NAME KEY
- download BUCKET_NAME SRC_FILE_NAME DEST_FILE_NAME KEY
- rotate BUCKET_NAME FILE_NAME OLD_KEY NEW_KEY
+Options:
+ --help Show help [boolean]
 
 Examples:
-
- node encryption generate-encryption-key
- node encryption upload my-bucket resources/test.txt file_encrypted.txt QxhqaZEqBGVTW55HhQw9Q=
- node encryption download my-bucket file_encrypted.txt ./file.txt QxhqaZEqBGVTW55HhQw9Q=
- node encryption rotate my-bucket file_encrypted.txt QxhqaZEqBGVTW55HhQw9Q= SxafpsdfSDFS89sds9Q=
+ node encryption generate-encryption-key Generate a sample encryption key.
+ node encryption upload my-bucket resources/test.txt Upload "resources/test.txt" to
+ file_encrypted.txt QxhqaZEqBGVTW55HhQw9Q= "gs://my-bucket/file_encrypted.txt".
+ node encryption download my-bucket file_encrypted.txt Download "gs://my-bucket/file_encrypted.txt" to
+ ./file.txt QxhqaZEqBGVTW55HhQw9Q= "./file.txt".
+ node encryption rotate my-bucket file_encrypted.txt Rotate encryptiong keys for
+ QxhqaZEqBGVTW55HhQw9Q= SxafpsdfSDFS89sds9Q= "gs://my-bucket/file_encrypted.txt".
+
+For more information, see https://cloud.google.com/storage/docs
 ```
 
 [encryption_docs]: https://cloud.google.com/storage/docs
@@ -123,32 +129,36 @@ View the [documentation][files_docs] or the [source code][files_code].
 __Usage:__ `node files --help`
 
 ```
-Usage: node files COMMAND [ARGS...]
-
 Commands:
+ list <bucket> [options] List files in a bucket, optionally filtering
+ by a prefix.
+ upload <bucket> <srcFile> Upload a local file to a bucket.
+ download <bucket> <srcFile> <destFile> Download a file from a bucket.
+ delete <bucket> <file> Delete a file from a bucket.
+ getMetadata <bucket> <file> Get metadata for a file in a bucket.
+ makePublic <bucket> <file> Make a file public in a bucket.
+ move <bucket> <srcFile> <destFile> Rename a file in a bucket.
+ copy <srcBucket> <srcFile> <destBucket> <destFile> Copy a file in a bucket to another bucket.
 
- list BUCKET_NAME
- listByPrefix BUCKET_NAME PREFIX [DELIMITER]
- upload BUCKET_NAME FILE_NAME
- download BUCKET_NAME SRC_FILE_NAME DEST_FILE_NAME
- delete BUCKET_NAME FILE_NAME
- getMetadata BUCKET_NAME FILE_NAME
- makePublic BUCKET_NAME FILE_NAME
- move BUCKET_NAME SRC_FILE_NAME DEST_FILE_NAME
- copy BUCKET_NAME SRC_FILE_NAME DEST_BUCKET_NAME DEST_FILE_NAME
+Options:
+ --help Show help [boolean]
 
 Examples:
-
- list my-bucket
- listByPrefix my-bucket /some-folder
- listByPrefix my-bucket /some-folder -
- upload my-bucket ./file.txt
- download my-bucket file.txt ./file.txt
- delete my-bucket file.txt
- getMetadata my-bucket file.txt
- makePublic my-bucket file.txt
- move my-bucket file.txt file2.txt
- copy my-bucket file.txt my-other-bucket file.txt
+ node files list my-bucket List files in "my-bucket".
+ node files list my-bucket -p public/ List files in "my-bucket" filtered by prefix
+ "public/".
+ node files upload my-bucket ./file.txt Upload "./file.txt" to "my-bucket".
+ node files download my-bucket file.txt ./file.txt Download "gs://my-bucket/file.txt" to
+ "./file.txt".
+ node files delete my-bucket file.txt Delete "gs://my-bucket/file.txt".
+ node files getMetadata my-bucket file.txt Get metadata for "gs://my-bucket/file.txt".
+ node files makePublic my-bucket file.txt Make "gs://my-bucket/file.txt" public.
+ node files move my-bucket file.txt file2.txt Rename "gs://my-bucket/file.txt" to
+ "gs://my-bucket/file2.txt".
+ node files copy my-bucket file.txt my-other-bucket Copy "gs://my-bucket/file.txt" to
+ file.txt "gs://my-other-bucket/file.txt".
+
+For more information, see https://cloud.google.com/storage/docs
 ```
 
 [files_docs]: https://cloud.google.com/storage/docs
@@ -161,41 +171,74 @@ View the [documentation][storagetransfer_docs] or the [source code][storagetrans
 __Usage:__ `node transfer --help`
 
 ```
-Usage: node encryption RESOURCE COMMAND [ARGS...]
+Commands:
+ jobs <cmd> [args] Run a job command.
+ operations <cmd> [args] Run an operation command.
 
-Resources:
+Options:
+ --help Show help [boolean]
 
- jobs
+Examples:
+ node transfer jobs --help Show job commands.
+ node transfer operations --help Show operations commands.
 
- Commands:
+For more information, see https://cloud.google.com/storage/transfer
+```
 
- create SRC_BUCKET_NAME DEST_BUCKET_NAME DATE TIME [DESCRIPTION]
- get JOB_NAME
- list
- set JOB_NAME FIELD VALUE
+__Usage:__ `node transfer jobs --help`
 
- operations
+```
+transfer jobs <cmd> [args]
 
- Commands:
+Commands:
+ create <srcBucket> <destBucket> <time> <date> Create a transfer job.
+ [description]
+ get <job> Get a transfer job.
+ list List transfer jobs.
+ set <job> <field> <value> Change the status, description or transferSpec
+ of a transfer job.
 
- list [JOB_NAME]
- get TRANSFER_NAME
- pause TRANSFER_NAME
- resume TRANSFER_NAME
+Options:
+ --help Show help [boolean]
 
 Examples:
+ node transfer jobs create my-bucket Create a transfer job.
+ my-other-bucket 2016/08/12 16:30 "Move my files"
+ node transfer jobs get Get a transfer job.
+ transferJobs/123456789012345678
+ node transfer jobs list List transfer jobs.
+ node transfer jobs set Update the description for a transfer job.
+ transferJobs/123456789012345678 description "My
+ new description"
+ node transfer jobs set Disable a transfer job.
+ transferJobs/123456789012345678 status DISABLED
+```
+
+__Usage:__ `node transfer operations --help`
+
+```
+transfer operations <cmd> [args]
+
+Commands:
+ list [job] List transfer operations, optionally filtering by a job name.
+ get <operation> Get a transfer operation.
+ pause <operation> Pause a transfer operation.
+ resume <operation> Resume a transfer operation.
 
- node transfer jobs create my-bucket my-other-bucket 2016/08/12 16:30 "Move my files"
- node transfer jobs get transferJobs/123456789012345678
- node transfer jobs list
- node transfer jobs set transferJobs/123456789012345678 description "My new description"
- node transfer jobs set transferJobs/123456789012345678 status DISABLED
- node transfer operations list
- node transfer operations list transferJobs/123456789012345678
- node transfer operations get transferOperations/123456789012345678
- node transfer operations pause transferOperations/123456789012345678
- node transfer operations resume transferOperations/123456789012345678
+Options:
+ --help Show help [boolean]
+
+Examples:
+ node transfer operations list List all transfer operations.
+ node transfer operations list List all transfer operations for a specific
+ transferJobs/123456789012345678 job.
+ node transfer operations get Get a transfer operation.
+ transferOperations/123456789012345678
+ node transfer operations pause Pause a transfer operation.
+ transferOperations/123456789012345678
+ node transfer operations resume Resume a transfer operation.
+ transferOperations/123456789012345678
 ```
 
-[storagetransfer_docs]: https://cloud.google.com/storage/docs
+[storagetransfer_docs]: https://cloud.google.com/storage/transfer
 [storagetransfer_code]: transfer.js

storage/acl.js

@@ -41,16 +41,16 @@ function addAccessControl (options, callback) {
  // Reference the specified storage bucket
  var bucket = storage.bucket(options.bucket);
  // Reference the bucket's acl resource
- // See https://googlecloudplatform.github.io/gcloud-node/#/docs/google-cloud/latest/storage/bucket?method=acl.add
+ // See https://googlecloudplatform.github.io/gcloud-node/#/docs/storage/latest/storage/bucket
  var acl = bucket.acl;
 
  if (options.file) {
  // Optionally target a file's acl resource
- // See https://googlecloudplatform.github.io/gcloud-node/#/docs/google-cloud/latest/storage/file?method=acl.add
+ // See https://googlecloudplatform.github.io/gcloud-node/#/docs/storage/latest/storage/file
  acl = bucket.file(options.file).acl;
  } else if (options.default) {
  // Optionally add "default" access controls to the bucket
- // See https://googlecloudplatform.github.io/gcloud-node/#/docs/google-cloud/latest/storage/bucket?method=acl.default.add
+ // See https://googlecloudplatform.github.io/gcloud-node/#/docs/storage/latest/storage/bucket
  acl = acl.default;
  }
 
@@ -86,16 +86,16 @@ function getAccessControl (options, callback) {
  // Reference the specified storage bucket
  var bucket = storage.bucket(options.bucket);
  // Reference the bucket's acl resource
- // See https://googlecloudplatform.github.io/gcloud-node/#/docs/google-cloud/latest/storage/bucket?method=acl.get
+ // See https://googlecloudplatform.github.io/gcloud-node/#/docs/storage/latest/storage/bucket
  var acl = bucket.acl;
 
  if (options.file) {
  // Optionally target a file's acl resource
-  // See https://googlecloudplatform.github.io/gcloud-node/#/docs/google-cloud/latest/storage/file?method=acl.get
+ // See https://googlecloudplatform.github.io/gcloud-node/#/docs/storage/latest/storage/file
  acl = bucket.file(options.file).acl;
  } else if (options.default) {
  // Optionally get "default" access controls for the bucket
-  // See https://googlecloudplatform.github.io/gcloud-node/#/docs/google-cloud/latest/storage/bucket?method=acl.default.get
+ // See https://googlecloudplatform.github.io/gcloud-node/#/docs/storage/latest/storage/bucket
  acl = acl.default;
  }
 
@@ -133,16 +133,16 @@ function deleteAccessControl (options, callback) {
  // Reference the specified storage bucket
  var bucket = storage.bucket(options.bucket);
  // Reference the bucket's acl resource
- // See https://googlecloudplatform.github.io/gcloud-node/#/docs/google-cloud/latest/storage/bucket?method=acl.delete
+ // See https://googlecloudplatform.github.io/gcloud-node/#/docs/storage/latest/storage/bucket
  var acl = bucket.acl;
 
  if (options.file) {
  // Optionally target a file's acl resource
-  // See https://googlecloudplatform.github.io/gcloud-node/#/docs/google-cloud/latest/storage/file?method=acl.delete
+ // See https://googlecloudplatform.github.io/gcloud-node/#/docs/storage/latest/storage/file
  acl = bucket.file(options.file).acl;
  } else if (options.default) {
  // Optionally delete "default" access controls from the bucket
-  // See https://googlecloudplatform.github.io/gcloud-node/#/docs/google-cloud/latest/storage/bucket?method=acl.default.delete
+ // See https://googlecloudplatform.github.io/gcloud-node/#/docs/storage/latest/storage/bucket
  acl = acl.default;
  }
 
@@ -173,6 +173,7 @@ var program = module.exports = {
 };
 
 cli
+ .demand(1)
  .command('add <entity> <role>', 'Add access controls on a bucket or file.', {}, function (options) {
  program.addAccessControl(options, console.log);
  })