gcloud 0.1.0 → 0.1.1

data/lib/gcloud/storage/bucket.rb

@@ -1,3 +1,4 @@
+#--
 # Copyright 2014 Google Inc. All rights reserved.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -19,7 +20,17 @@ require "gcloud/storage/file"
 module Gcloud
   module Storage
     ##
-    # Represents a Bucket. Belongs to a Project and has many Files.
+    # = Bucket
+    #
+    # Represents a Storage bucket. Belongs to a Project and has many Files.
+    #
+    #   require "glcoud/storage"
+    #
+    #   storage = Gcloud.storage
+    #
+    #   bucket = storage.find_bucket "my-bucket"
+    #   file = bucket.find_file "path/to/my-file.ext"
+    #
     class Bucket
       ##
       # The Connection object.
@@ -31,14 +42,14 @@ module Gcloud
 
       ##
       # Create an empty Bucket object.
-      def initialize
+      def initialize #:nodoc:
         @connection = nil
         @gapi = {}
       end
 
       ##
       # The kind of item this is.
-      # For buckets, this is always storage#bucket.
+      # For buckets, this is always +storage#bucket+.
       def kind
         @gapi["kind"]
       end
@@ -80,15 +91,40 @@ module Gcloud
 
       ##
       # Permenently deletes the bucket.
-      # The bucket must be empty.
+      # The bucket must be empty before it can be deleted.
       #
+      # === Parameters
+      #
+      # +options+::
+      #   An optional Hash for controlling additional behavor. (+Hash+)
+      # +options [:retries]+::
+      #   The number of times the API call should be retried.
+      #   Default is Gcloud::Backoff.retries. (+Integer+)
+      #
+      # === Returns
+      #
+      # +true+ if the bucket was deleted.
+      #
+      # === Examples
+      #
+      #   require "gcloud/storage"
+      #
+      #   storage = Gcloud.storage
+      #
+      #   bucket = storage.find_bucket "my-bucket"
       #   bucket.delete
       #
       # The API call to delete the bucket may be retried under certain
       # conditions. See Gcloud::Backoff to control this behavior, or
       # specify the wanted behavior in the call:
       #
+      #   require "gcloud/storage"
+      #
+      #   storage = Gcloud.storage
+      #
+      #   bucket = storage.find_bucket "my-bucket"
       #   bucket.delete retries: 5
+      #
       def delete options = {}
         ensure_connection!
         resp = connection.delete_bucket name, options
@@ -102,14 +138,66 @@ module Gcloud
       ##
       # Retrieves a list of files matching the criteria.
       #
+      # === Parameters
+      #
+      # +options+::
+      #   An optional Hash for controlling additional behavor. (+Hash+)
+      # +options [:prefix]+::
+      #   Filter results to files whose names begin with this prefix.
+      #   (+String+)
+      # +options [:token]+::
+      #   A previously-returned page token representing part of the larger set
+      #   of results to view. (+String+)
+      # +options [:max]+::
+      #   Maximum number of items plus prefixes to return. As duplicate prefixes
+      #   are omitted, fewer total results may be returned than requested.
+      #   The default value of this parameter is 1,000 items. (+Integer+)
+      # +options [:versions]+::
+      #   If +true+, lists all versions of an object as distinct results.
+      #   The default is +false+. For more information, see
+      #   {Object Versioning
+      #   }[https://cloud.google.com/storage/docs/object-versioning].
+      #   (+Boolean+)
+      # +options [:max]+::
+      #   Maximum number of buckets to return. (+Integer+)
+      #
+      # === Returns
+      #
+      # Array of Gcloud::Datastore::File (Gcloud::Datastore::File::List)
+      #
+      # === Examples
+      #
+      #   require "gcloud/storage"
+      #
       #   storage = Gcloud.storage
+      #
       #   bucket = storage.find_bucket "my-bucket"
       #   files = bucket.files
       #   files.each do |file|
       #     puts file.name
       #   end
       #
-      # See Gcloud::Storage::File
+      # If you have a significant number of files, you may need to paginate
+      # through them: (See File::List#token)
+      #
+      #   require "gcloud/storage"
+      #
+      #   storage = Gcloud.storage
+      #
+      #   bucket = storage.find_bucket "my-bucket"
+      #
+      #   all_files = []
+      #   tmp_files = bucket.files
+      #   while tmp_files.any? do
+      #     tmp_files.each do |file|
+      #       all_files << file
+      #     end
+      #     # break loop if no more buckets available
+      #     break if tmp_files.token.nil?
+      #     # get the next group of files
+      #     tmp_files = bucket.files token: tmp_files.token
+      #   end
+      #
       def files options = {}
         ensure_connection!
         resp = connection.list_files name, options
@@ -123,12 +211,26 @@ module Gcloud
       ##
       # Retrieves a file matching the path.
       #
+      # === Parameters
+      #
+      # +path+::
+      #   Name (path) of the file. (+String+)
+      #
+      # === Returns
+      #
+      # Gcloud::Datastore::File or nil if file does not exist
+      #
+      # === Example
+      #
+      #   require "gcloud/storage"
+      #
       #   storage = Gcloud.storage
+      #
       #   bucket = storage.find_bucket "my-bucket"
+      #
       #   file = bucket.find_file "path/to/my-file.ext"
       #   puts file.name
       #
-      # See Gcloud::Storage::File
       def find_file path, options = {}
         ensure_connection!
         resp = connection.get_file name, path, options
@@ -140,17 +242,57 @@ module Gcloud
       end
 
       ##
-      # Create a new Gcloud::Storeage::File object by providing a
-      # File object to upload and the path to store it with.
+      # Create a new File object by providing a path to a local file to upload
+      # and the path to store it with in the bucket.
+      #
+      # === Parameters
+      #
+      # +file+::
+      #   Path of the file on the filesystem to upload. (+String+)
+      # +path+::
+      #   Path to store the file in Google Cloud Storage. (+String+)
+      # +options+::
+      #   An optional Hash for controlling additional behavor. (+Hash+)
+      # +options [:acl]+::
+      #   A predefined set of access controls to apply to this file.
+      #   (+String+)
+      #
+      #   Acceptable values are:
+      #   * +auth+, +auth_read+, +authenticated+, +authenticated_read+,
+      #     +authenticatedRead+:: File owner gets OWNER access, and
+      #     allAuthenticatedUsers get READER access.
+      #   * +owner_full+, +bucketOwnerFullControl+:: File owner gets OWNER
+      #     access, and project team owners get OWNER access.
+      #   * +owner_read+, +bucketOwnerRead+:: File owner gets OWNER access, and
+      #     project team owners get READER access.
+      #   * +private+:: File owner gets OWNER access.
+      #   * +project_private+, +projectPrivate+:: File owner gets OWNER access,
+      #     and project team members get access according to their roles.
+      #   * +public+, +public_read+, +publicRead+:: File owner gets OWNER
+      #     access, and allUsers get READER access.
+      #
+      # === Returns
+      #
+      # Gcloud::Datastore::File
+      #
+      # === Examples
+      #
+      #   require "gcloud/storage"
       #
       #   storage = Gcloud.storage
+      #
       #   bucket = storage.find_bucket "my-bucket"
+      #
       #   bucket.create_file "path/to/local.file.ext"
       #
       # Additionally, a destination path can be specified.
       #
+      #   require "gcloud/storage"
+      #
       #   storage = Gcloud.storage
+      #
       #   bucket = storage.find_bucket "my-bucket"
+      #
       #   bucket.create_file "path/to/local.file.ext",
       #                      "destination/path/file.ext"
       #
@@ -160,11 +302,16 @@ module Gcloud
       # by 265KB then it will be lowered to the nearest acceptible
       # value.
       #
+      #   require "gcloud/storage"
+      #
+      #   storage = Gcloud.storage
+      #
+      #   bucket = storage.find_bucket "my-bucket"
+      #
       #   bucket.create_file "path/to/local.file.ext",
       #                      "destination/path/file.ext",
       #                      chunk_size: 1024*1024 # 1 MB chunk
       #
-      # See Gcloud::Storage::File
       def create_file file, path = nil, options = {}
         ensure_connection!
         # TODO: Raise if file doesn't exist
@@ -181,13 +328,103 @@ module Gcloud
       end
 
       ##
-      # Access Control List
+      # The Bucket::Acl instance used to control access to the bucket.
+      #
+      # A bucket has owners, writers, and readers. Permissions can be granted to
+      # an individual user's email address, a group's email address, as well as
+      # many predefined lists. See the
+      # {Access Control guide
+      # }[https://cloud.google.com/storage/docs/access-control]
+      # for more.
+      #
+      # === Examples
+      #
+      # Access to a bucket can be granted to a user by appending +"user-"+ to
+      # the email address:
+      #
+      #   require "gcloud/storage"
+      #
+      #   storage = Gcloud.storage
+      #
+      #   bucket = storage.find_bucket "my-todo-app"
+      #
+      #   email = "heidi@example.net"
+      #   bucket.acl.add_reader "user-#{email}"
+      #
+      # Access to a bucket can be granted to a group by appending +"group-"+ to
+      # the email address:
+      #
+      #   require "gcloud/storage"
+      #
+      #   storage = Gcloud.storage
+      #
+      #   bucket = storage.find_bucket "my-todo-app"
+      #
+      #   email = "authors@example.net"
+      #   bucket.acl.add_reader "group-#{email}"
+      #
+      # Access to a bucket can also be granted to a predefined list of
+      # permissions:
+      #
+      #   require "gcloud/storage"
+      #
+      #   storage = Gcloud.storage
+      #
+      #   bucket = storage.find_bucket "my-todo-app"
+      #
+      #   bucket.acl.public!
+      #
       def acl
         @acl ||= Bucket::Acl.new self
       end
 
       ##
-      # Default Access Control List
+      # The Bucket::DefaultAcl instance used to control access to the bucket's
+      # files.
+      #
+      # A bucket's files have owners, writers, and readers. Permissions can be
+      # granted to an individual user's email address, a group's email address,
+      # as well as many predefined lists. See the
+      # {Access Control guide
+      # }[https://cloud.google.com/storage/docs/access-control]
+      # for more.
+      #
+      # === Examples
+      #
+      # Access to a bucket's files can be granted to a user by appending
+      # +"user-"+ to the email address:
+      #
+      #   require "gcloud/storage"
+      #
+      #   storage = Gcloud.storage
+      #
+      #   bucket = storage.find_bucket "my-todo-app"
+      #
+      #   email = "heidi@example.net"
+      #   bucket.default_acl.add_reader "user-#{email}"
+      #
+      # Access to a bucket's files can be granted to a group by appending
+      # +"group-"+ to the email address:
+      #
+      #   require "gcloud/storage"
+      #
+      #   storage = Gcloud.storage
+      #
+      #   bucket = storage.find_bucket "my-todo-app"
+      #
+      #   email = "authors@example.net"
+      #   bucket.default_acl.add_reader "group-#{email}"
+      #
+      # Access to a bucket's files can also be granted to a predefined list of
+      # permissions:
+      #
+      #   require "gcloud/storage"
+      #
+      #   storage = Gcloud.storage
+      #
+      #   bucket = storage.find_bucket "my-todo-app"
+      #
+      #   bucket.default_acl.public!
       def default_acl
         @default_acl ||= Bucket::DefaultAcl.new self
       end

data/lib/gcloud/storage/bucket/acl.rb

@@ -1,3 +1,4 @@
+#--
 # Copyright 2015 Google Inc. All rights reserved.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -16,7 +17,18 @@ module Gcloud
   module Storage
     class Bucket
       ##
+      # = Bucket Access Control List
+      #
       # Represents a Bucket's Access Control List.
+      #
+      #   require "glcoud/storage"
+      #
+      #   storage = Gcloud.storage
+      #
+      #   bucket = storage.find_bucket "my-bucket"
+      #
+      #   bucket.acl.readers.each { |reader| puts reader }
+      #
       class Acl
         RULES = { "authenticatedRead" => "authenticatedRead",
                   "auth" => "authenticatedRead",
@@ -31,7 +43,7 @@ module Gcloud
                   "public" => "publicRead",
                   "public_read" => "publicRead",
                   "publicReadWrite" => "publicReadWrite",
-                  "public_write" => "publicReadWrite" }
+                  "public_write" => "publicReadWrite" } #:nodoc:
 
         ##
         # Initialized a new Acl object.
@@ -44,6 +56,19 @@ module Gcloud
           @readers = nil
         end
 
+        ##
+        # Reloads all Access Control List data for the bucket.
+        #
+        # === Example
+        #
+        #   require "glcoud/storage"
+        #
+        #   storage = Gcloud.storage
+        #
+        #   bucket = storage.find_bucket "my-bucket"
+        #
+        #   bucket.acl.refresh!
+        #
         def refresh!
           resp = @connection.list_bucket_acls @bucket
           acls = resp.data["items"]
@@ -52,21 +77,116 @@ module Gcloud
           @readers = entities_from_acls acls, "READER"
         end
 
+        ##
+        # Lists the owners of the bucket.
+        #
+        # === Returns
+        #
+        # Array of Strings
+        #
+        # === Example
+        #
+        #   require "glcoud/storage"
+        #
+        #   storage = Gcloud.storage
+        #
+        #   bucket = storage.find_bucket "my-bucket"
+        #
+        #   bucket.acl.owners.each { |owner| puts owner }
+        #
         def owners
           refresh! if @owners.nil?
           @owners
         end
 
+        ##
+        # Lists the owners of the bucket.
+        #
+        # === Returns
+        #
+        # Array of Strings
+        #
+        # === Example
+        #
+        #   require "glcoud/storage"
+        #
+        #   storage = Gcloud.storage
+        #
+        #   bucket = storage.find_bucket "my-bucket"
+        #
+        #   bucket.acl.writers.each { |writer| puts writer }
+        #
         def writers
           refresh! if @writers.nil?
           @writers
         end
 
+        ##
+        # Lists the readers of the bucket.
+        #
+        # === Returns
+        #
+        # Array of Strings
+        #
+        # === Example
+        #
+        #   require "glcoud/storage"
+        #
+        #   storage = Gcloud.storage
+        #
+        #   bucket = storage.find_bucket "my-bucket"
+        #
+        #   bucket.acl.readers.each { |reader| puts reader }
+        #
         def readers
           refresh! if @readers.nil?
           @readers
         end
 
+        ##
+        # Grants owner permission to the bucket.
+        #
+        # === Parameters
+        #
+        # +entity+::
+        #   The entity holding the permission, in one of the following forms:
+        #   (+String+)
+        #
+        #   * user-userId
+        #   * user-email
+        #   * group-groupId
+        #   * group-email
+        #   * domain-domain
+        #   * project-team-projectId
+        #   * allUsers
+        #   * allAuthenticatedUsers
+        #
+        # === Examples
+        #
+        # Access to a bucket can be granted to a user by appending +"user-"+ to
+        # the email address:
+        #
+        #   require "glcoud/storage"
+        #
+        #   storage = Gcloud.storage
+        #
+        #   bucket = storage.find_bucket "my-bucket"
+        #
+        #   email = "heidi@example.net"
+        #   bucket.acl.add_owner "user-#{email}"
+        #
+        # Access to a bucket can be granted to a group by appending +"group-"+
+        # to the email address:
+        #
+        #   require "glcoud/storage"
+        #
+        #   storage = Gcloud.storage
+        #
+        #   bucket = storage.find_bucket "my-bucket"
+        #
+        #   email = "authors@example.net"
+        #   bucket.acl.add_owner "group-#{email}"
+        #
         def add_owner entity
           resp = @connection.insert_bucket_acl @bucket, entity, "OWNER"
           if resp.success?
@@ -77,6 +197,50 @@ module Gcloud
           nil
         end
 
+        ##
+        # Grants writer permission to the bucket.
+        #
+        # === Parameters
+        #
+        # +entity+::
+        #   The entity holding the permission, in one of the following forms:
+        #   (+String+)
+        #
+        #   * user-userId
+        #   * user-email
+        #   * group-groupId
+        #   * group-email
+        #   * domain-domain
+        #   * project-team-projectId
+        #   * allUsers
+        #   * allAuthenticatedUsers
+        #
+        # === Examples
+        #
+        # Access to a bucket can be granted to a user by appending +"user-"+ to
+        # the email address:
+        #
+        #   require "glcoud/storage"
+        #
+        #   storage = Gcloud.storage
+        #
+        #   bucket = storage.find_bucket "my-bucket"
+        #
+        #   email = "heidi@example.net"
+        #   bucket.acl.add_writer "user-#{email}"
+        #
+        # Access to a bucket can be granted to a group by appending +"group-"+
+        # to the email address:
+        #
+        #   require "glcoud/storage"
+        #
+        #   storage = Gcloud.storage
+        #
+        #   bucket = storage.find_bucket "my-bucket"
+        #
+        #   email = "authors@example.net"
+        #   bucket.acl.add_writer "group-#{email}"
+        #
         def add_writer entity
           resp = @connection.insert_bucket_acl @bucket, entity, "WRITER"
           if resp.success?
@@ -87,6 +251,50 @@ module Gcloud
           nil
         end
 
+        ##
+        # Grants reader permission to the bucket.
+        #
+        # === Parameters
+        #
+        # +entity+::
+        #   The entity holding the permission, in one of the following forms:
+        #   (+String+)
+        #
+        #   * user-userId
+        #   * user-email
+        #   * group-groupId
+        #   * group-email
+        #   * domain-domain
+        #   * project-team-projectId
+        #   * allUsers
+        #   * allAuthenticatedUsers
+        #
+        # === Examples
+        #
+        # Access to a bucket can be granted to a user by appending +"user-"+ to
+        # the email address:
+        #
+        #   require "glcoud/storage"
+        #
+        #   storage = Gcloud.storage
+        #
+        #   bucket = storage.find_bucket "my-bucket"
+        #
+        #   email = "heidi@example.net"
+        #   bucket.acl.add_reader "user-#{email}"
+        #
+        # Access to a bucket can be granted to a group by appending +"group-"+
+        # to the email address:
+        #
+        #   require "glcoud/storage"
+        #
+        #   storage = Gcloud.storage
+        #
+        #   bucket = storage.find_bucket "my-bucket"
+        #
+        #   email = "authors@example.net"
+        #   bucket.acl.add_reader "group-#{email}"
+        #
         def add_reader entity
           resp = @connection.insert_bucket_acl @bucket, entity, "READER"
           if resp.success?
@@ -97,6 +305,35 @@ module Gcloud
           nil
         end
 
+        ##
+        # Permenently deletes the entity from the bucket's access control list.
+        #
+        # === Parameters
+        #
+        # +entity+::
+        #   The entity holding the permission, in one of the following forms:
+        #   (+String+)
+        #
+        #   * user-userId
+        #   * user-email
+        #   * group-groupId
+        #   * group-email
+        #   * domain-domain
+        #   * project-team-projectId
+        #   * allUsers
+        #   * allAuthenticatedUsers
+        #
+        # === Example
+        #
+        #   require "glcoud/storage"
+        #
+        #   storage = Gcloud.storage
+        #
+        #   bucket = storage.find_bucket "my-bucket"
+        #
+        #   email = "heidi@example.net"
+        #   bucket.acl.delete "user-#{email}"
+        #
         def delete entity
           resp = @connection.delete_bucket_acl @bucket, entity
           if resp.success?
@@ -108,12 +345,26 @@ module Gcloud
           false
         end
 
-        def self.predefined_rule_for rule_name
+        def self.predefined_rule_for rule_name #:nodoc:
           RULES[rule_name.to_s]
         end
 
         # Predefined ACL helpers
 
+        ##
+        # Convenience method to apply the +authenticatedRead+ predefined ACL
+        # rule to the bucket.
+        #
+        # === Example
+        #
+        #   require "glcoud/storage"
+        #
+        #   storage = Gcloud.storage
+        #
+        #   bucket = storage.find_bucket "my-bucket"
+        #
+        #   bucket.acl.auth!
+        #
         def auth!
           update_predefined_acl! "authenticatedRead"
         end
@@ -122,21 +373,76 @@ module Gcloud
         alias_method :authenticated!, :auth!
         alias_method :authenticated_read!, :auth!
 
+        ##
+        # Convenience method to apply the +private+ predefined ACL
+        # rule to the bucket.
+        #
+        # === Example
+        #
+        #   require "glcoud/storage"
+        #
+        #   storage = Gcloud.storage
+        #
+        #   bucket = storage.find_bucket "my-bucket"
+        #
+        #   bucket.acl.private!
+        #
         def private!
           update_predefined_acl! "private"
         end
 
+        ##
+        # Convenience method to apply the +projectPrivate+ predefined ACL
+        # rule to the bucket.
+        #
+        # === Example
+        #
+        #   require "glcoud/storage"
+        #
+        #   storage = Gcloud.storage
+        #
+        #   bucket = storage.find_bucket "my-bucket"
+        #
+        #   bucket.acl.project_private!
+        #
         def project_private!
           update_predefined_acl! "projectPrivate"
         end
         alias_method :projectPrivate!, :project_private!
 
+        ##
+        # Convenience method to apply the +publicRead+ predefined ACL
+        # rule to the bucket.
+        #
+        # === Example
+        #
+        #   require "glcoud/storage"
+        #
+        #   storage = Gcloud.storage
+        #
+        #   bucket = storage.find_bucket "my-bucket"
+        #
+        #   bucket.acl.public!
+        #
         def public!
           update_predefined_acl! "publicRead"
         end
         alias_method :publicRead!, :public!
         alias_method :public_read!, :public!
 
+        # Convenience method to apply the +publicReadWrite+ predefined ACL
+        # rule to the bucket.
+        #
+        # === Example
+        #
+        #   require "glcoud/storage"
+        #
+        #   storage = Gcloud.storage
+        #
+        #   bucket = storage.find_bucket "my-bucket"
+        #
+        #   bucket.acl.public_write!
+        #
         def public_write!
           update_predefined_acl! "publicReadWrite"
         end
@@ -159,7 +465,18 @@ module Gcloud
       end
 
       ##
+      # = Bucket Default Access Control List
+      #
       # Represents a Bucket's Default Access Control List.
+      #
+      #   require "glcoud/storage"
+      #
+      #   storage = Gcloud.storage
+      #
+      #   bucket = storage.find_bucket "my-bucket"
+      #
+      #   bucket.default_acl.readers.each { |reader| puts reader }
+      #
       class DefaultAcl
         RULES = { "authenticatedRead" => "authenticatedRead",
                   "auth" => "authenticatedRead",
@@ -175,7 +492,7 @@ module Gcloud
                   "project_private" => "projectPrivate",
                   "publicRead" => "publicRead",
                   "public" => "publicRead",
-                  "public_read" => "publicRead" }
+                  "public_read" => "publicRead" } #:nodoc:
 
         ##
         # Initialized a new DefaultAcl object.
@@ -188,6 +505,19 @@ module Gcloud
           @readers = nil
         end
 
+        ##
+        # Reloads all Default Access Control List data for the bucket.
+        #
+        # === Example
+        #
+        #   require "glcoud/storage"
+        #
+        #   storage = Gcloud.storage
+        #
+        #   bucket = storage.find_bucket "my-bucket"
+        #
+        #   bucket.default_acl.refresh!
+        #
         def refresh!
           resp = @connection.list_default_acls @bucket
           acls = resp.data["items"]
@@ -196,21 +526,116 @@ module Gcloud
           @readers = entities_from_acls acls, "READER"
         end
 
+        ##
+        # Lists the default owners for files in the bucket.
+        #
+        # === Returns
+        #
+        # Array of Strings
+        #
+        # === Example
+        #
+        #   require "glcoud/storage"
+        #
+        #   storage = Gcloud.storage
+        #
+        #   bucket = storage.find_bucket "my-bucket"
+        #
+        #   bucket.default_acl.owners.each { |owner| puts owner }
+        #
         def owners
           refresh! if @owners.nil?
           @owners
         end
 
+        ##
+        # Lists the default writers for files in the bucket.
+        #
+        # === Returns
+        #
+        # Array of Strings
+        #
+        # === Example
+        #
+        #   require "glcoud/storage"
+        #
+        #   storage = Gcloud.storage
+        #
+        #   bucket = storage.find_bucket "my-bucket"
+        #
+        #   bucket.default_acl.writers.each { |writer| puts writer }
+        #
         def writers
           refresh! if @writers.nil?
           @writers
         end
 
+        ##
+        # Lists the default readers for files in the bucket.
+        #
+        # === Returns
+        #
+        # Array of Strings
+        #
+        # === Example
+        #
+        #   require "glcoud/storage"
+        #
+        #   storage = Gcloud.storage
+        #
+        #   bucket = storage.find_bucket "my-bucket"
+        #
+        #   bucket.default_acl.readers.each { |reader| puts reader }
+        #
         def readers
           refresh! if @readers.nil?
           @readers
         end
 
+        ##
+        # Grants default owner permission to files in the bucket.
+        #
+        # === Parameters
+        #
+        # +entity+::
+        #   The entity holding the permission, in one of the following forms:
+        #   (+String+)
+        #
+        #   * user-userId
+        #   * user-email
+        #   * group-groupId
+        #   * group-email
+        #   * domain-domain
+        #   * project-team-projectId
+        #   * allUsers
+        #   * allAuthenticatedUsers
+        #
+        # === Examples
+        #
+        # Access to a bucket can be granted to a user by appending +"user-"+ to
+        # the email address:
+        #
+        #   require "glcoud/storage"
+        #
+        #   storage = Gcloud.storage
+        #
+        #   bucket = storage.find_bucket "my-bucket"
+        #
+        #   email = "heidi@example.net"
+        #   bucket.default_acl.add_owner "user-#{email}"
+        #
+        # Access to a bucket can be granted to a group by appending +"group-"+
+        # to the email address:
+        #
+        #   require "glcoud/storage"
+        #
+        #   storage = Gcloud.storage
+        #
+        #   bucket = storage.find_bucket "my-bucket"
+        #
+        #   email = "authors@example.net"
+        #   bucket.default_acl.add_owner "group-#{email}"
+        #
         def add_owner entity
           resp = @connection.insert_default_acl @bucket, entity, "OWNER"
           if resp.success?
@@ -221,6 +646,50 @@ module Gcloud
           nil
         end
 
+        ##
+        # Grants default writer permission to files in the bucket.
+        #
+        # === Parameters
+        #
+        # +entity+::
+        #   The entity holding the permission, in one of the following forms:
+        #   (+String+)
+        #
+        #   * user-userId
+        #   * user-email
+        #   * group-groupId
+        #   * group-email
+        #   * domain-domain
+        #   * project-team-projectId
+        #   * allUsers
+        #   * allAuthenticatedUsers
+        #
+        # === Examples
+        #
+        # Access to a bucket can be granted to a user by appending +"user-"+ to
+        # the email address:
+        #
+        #   require "glcoud/storage"
+        #
+        #   storage = Gcloud.storage
+        #
+        #   bucket = storage.find_bucket "my-bucket"
+        #
+        #   email = "heidi@example.net"
+        #   bucket.default_acl.add_writer "user-#{email}"
+        #
+        # Access to a bucket can be granted to a group by appending +"group-"+
+        # to the email address:
+        #
+        #   require "glcoud/storage"
+        #
+        #   storage = Gcloud.storage
+        #
+        #   bucket = storage.find_bucket "my-bucket"
+        #
+        #   email = "authors@example.net"
+        #   bucket.default_acl.add_writer "group-#{email}"
+        #
         def add_writer entity
           resp = @connection.insert_default_acl @bucket, entity, "WRITER"
           if resp.success?
@@ -231,6 +700,50 @@ module Gcloud
           nil
         end
 
+        ##
+        # Grants default reader permission to files in the bucket.
+        #
+        # === Parameters
+        #
+        # +entity+::
+        #   The entity holding the permission, in one of the following forms:
+        #   (+String+)
+        #
+        #   * user-userId
+        #   * user-email
+        #   * group-groupId
+        #   * group-email
+        #   * domain-domain
+        #   * project-team-projectId
+        #   * allUsers
+        #   * allAuthenticatedUsers
+        #
+        # === Examples
+        #
+        # Access to a bucket can be granted to a user by appending +"user-"+ to
+        # the email address:
+        #
+        #   require "glcoud/storage"
+        #
+        #   storage = Gcloud.storage
+        #
+        #   bucket = storage.find_bucket "my-bucket"
+        #
+        #   email = "heidi@example.net"
+        #   bucket.default_acl.add_reader "user-#{email}"
+        #
+        # Access to a bucket can be granted to a group by appending +"group-"+
+        # to the email address:
+        #
+        #   require "glcoud/storage"
+        #
+        #   storage = Gcloud.storage
+        #
+        #   bucket = storage.find_bucket "my-bucket"
+        #
+        #   email = "authors@example.net"
+        #   bucket.default_acl.add_reader "group-#{email}"
+        #
         def add_reader entity
           resp = @connection.insert_default_acl @bucket, entity, "READER"
           if resp.success?
@@ -241,6 +754,36 @@ module Gcloud
           nil
         end
 
+        ##
+        # Permenently deletes the entity from the bucket's default access
+        # control list for files.
+        #
+        # === Parameters
+        #
+        # +entity+::
+        #   The entity holding the permission, in one of the following forms:
+        #   (+String+)
+        #
+        #   * user-userId
+        #   * user-email
+        #   * group-groupId
+        #   * group-email
+        #   * domain-domain
+        #   * project-team-projectId
+        #   * allUsers
+        #   * allAuthenticatedUsers
+        #
+        # === Example
+        #
+        #   require "glcoud/storage"
+        #
+        #   storage = Gcloud.storage
+        #
+        #   bucket = storage.find_bucket "my-bucket"
+        #
+        #   email = "heidi@example.net"
+        #   bucket.default_acl.delete "user-#{email}"
+        #
         def delete entity
           resp = @connection.delete_default_acl @bucket, entity
           if resp.success?
@@ -252,12 +795,26 @@ module Gcloud
           false
         end
 
-        def self.predefined_rule_for rule_name
+        def self.predefined_rule_for rule_name #:nodoc:
           RULES[rule_name.to_s]
         end
 
         # Predefined ACL helpers
 
+        ##
+        # Convenience method to apply the default +authenticatedRead+
+        # predefined ACL rule to files in the bucket.
+        #
+        # === Example
+        #
+        #   require "glcoud/storage"
+        #
+        #   storage = Gcloud.storage
+        #
+        #   bucket = storage.find_bucket "my-bucket"
+        #
+        #   bucket.acl.auth!
+        #
         def auth!
           update_predefined_default_acl! "authenticatedRead"
         end
@@ -266,25 +823,95 @@ module Gcloud
         alias_method :authenticated!, :auth!
         alias_method :authenticated_read!, :auth!
 
+        ##
+        # Convenience method to apply the default +bucketOwnerFullControl+
+        # predefined ACL rule to files in the bucket.
+        #
+        # === Example
+        #
+        #   require "glcoud/storage"
+        #
+        #   storage = Gcloud.storage
+        #
+        #   bucket = storage.find_bucket "my-bucket"
+        #
+        #   bucket.acl.owner_full!
+        #
         def owner_full!
           update_predefined_default_acl! "bucketOwnerFullControl"
         end
         alias_method :bucketOwnerFullControl!, :owner_full!
 
+        ##
+        # Convenience method to apply the default +bucketOwnerRead+
+        # predefined ACL rule to files in the bucket.
+        #
+        # === Example
+        #
+        #   require "glcoud/storage"
+        #
+        #   storage = Gcloud.storage
+        #
+        #   bucket = storage.find_bucket "my-bucket"
+        #
+        #   bucket.acl.owner_read!
+        #
         def owner_read!
           update_predefined_default_acl! "bucketOwnerRead"
         end
         alias_method :bucketOwnerRead!, :owner_read!
 
+        ##
+        # Convenience method to apply the default +private+
+        # predefined ACL rule to files in the bucket.
+        #
+        # === Example
+        #
+        #   require "glcoud/storage"
+        #
+        #   storage = Gcloud.storage
+        #
+        #   bucket = storage.find_bucket "my-bucket"
+        #
+        #   bucket.acl.private!
+        #
         def private!
           update_predefined_default_acl! "private"
         end
 
+        ##
+        # Convenience method to apply the default +projectPrivate+
+        # predefined ACL rule to files in the bucket.
+        #
+        # === Example
+        #
+        #   require "glcoud/storage"
+        #
+        #   storage = Gcloud.storage
+        #
+        #   bucket = storage.find_bucket "my-bucket"
+        #
+        #   bucket.acl.project_private!
+        #
         def project_private!
           update_predefined_default_acl! "projectPrivate"
         end
         alias_method :projectPrivate!, :project_private!
 
+        ##
+        # Convenience method to apply the default +publicRead+
+        # predefined ACL rule to files in the bucket.
+        #
+        # === Example
+        #
+        #   require "glcoud/storage"
+        #
+        #   storage = Gcloud.storage
+        #
+        #   bucket = storage.find_bucket "my-bucket"
+        #
+        #   bucket.acl.public!
+        #
         def public!
           update_predefined_default_acl! "publicRead"
         end