storage: docs - explain scope values - fixes #319

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).
  *