From 43a850cd72a363a131e54ab760214c66a1fa4d35 Mon Sep 17 00:00:00 2001
From: Stephen Sawchuk <sawchuk@gmail.com>
Date: Thu, 4 Dec 2014 12:23:29 -0500
Subject: [PATCH] storage: docs - explain scope values - fixes #319

---
 lib/storage/acl.js | 24 ++++++++++++++++++++++++
 1 file changed, 24 insertions(+)

diff --git a/lib/storage/acl.js b/lib/storage/acl.js
index 679ec5a0085..05df9b36115 100644
--- a/lib/storage/acl.js
+++ b/lib/storage/acl.js
@@ -36,6 +36,30 @@ var util = require('../common/util.js');
  * object or bucket (for example, `READ` or `WRITE`); the scope defines who the
  * permission applies to (for example, a specific user or group of users).
  *
+ * Where a `scope` value is accepted, we follow the format the Cloud Storage API
+ * expects.
+ *
+ * Refer to
+ * https://cloud.google.com/storage/docs/json_api/v1/defaultObjectAccessControls
+ * for the most up-to-date values.
+ *
+ *   - `user-userId`
+ *   - `user-email`
+ *   - `group-groupId`
+ *   - `group-email`
+ *   - `domain-domain`
+ *   - `project-team-projectId`
+ *   - `allUsers`
+ *   - `allAuthenticatedUsers`
+ *
+ * Examples:
+ *
+ *   - The user "liz@example.com" would be `user-liz@example.com`.
+ *   - The group "example@googlegroups.com" would be
+ *     `group-example@googlegroups.com`.
+ *   - To refer to all members of the Google Apps for Business domain
+ *     "example.com", the entity would be `domain-example.com`.
+ *
  * For more detailed information, see
  * [About Access Control Lists](http://goo.gl/6qBBPO).
  *