gcloud 0.1.0 → 0.1.1

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

@@ -1,3 +1,4 @@
+#--
 # Copyright 2015 Google Inc. All rights reserved.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");

data/lib/gcloud/storage/connection.rb

@@ -1,3 +1,4 @@
+#--
 # Copyright 2014 Google Inc. All rights reserved.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");

data/lib/gcloud/storage/credentials.rb

@@ -1,3 +1,4 @@
+#--
 # Copyright 2014 Google Inc. All rights reserved.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -20,7 +21,8 @@ module Gcloud
     # Represents the Oauth2 signing logic for Storage.
     class Credentials < Gcloud::Credentials #:nodoc:
       SCOPE = ["https://www.googleapis.com/auth/devstorage.full_control"]
-      ENV_VARS = ["STORAGE_KEYFILE"]
+      PATH_ENV_VARS = %w(STORAGE_KEYFILE GOOGLE_CLOUD_KEYFILE)
+      JSON_ENV_VARS = %w(STORAGE_KEYFILE_JSON GOOGLE_CLOUD_KEYFILE_JSON)
     end
   end
 end

data/lib/gcloud/storage/errors.rb

@@ -1,3 +1,4 @@
+#--
 # Copyright 2014 Google Inc. All rights reserved.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -15,11 +16,15 @@
 module Gcloud
   module Storage
     ##
+    # = Storage Error
+    #
     # Base Storage exception class.
     class Error < Gcloud::Error
     end
 
     ##
+    # = ApiError
+    #
     # Raised when an API call is not successful.
     class ApiError < Error
       ##
@@ -32,7 +37,8 @@ module Gcloud
 
       def initialize message, code, errors
         super message
-        @code, @errors = code, errors
+        @code   = code
+        @errors = errors
       end
 
       def self.from_response resp #:nodoc:
@@ -43,6 +49,8 @@ module Gcloud
     end
 
     ##
+    # = FileVerificationError
+    #
     # Raised when a File download fails the verification.
     class FileVerificationError < Error
       ##

data/lib/gcloud/storage/file.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,19 @@ require "gcloud/storage/file/verifier"
 module Gcloud
   module Storage
     ##
+    # = File
+    #
     # Represents the File/Object that belong to a Bucket.
+    #
+    #   require "glcoud/storage"
+    #
+    #   storage = Gcloud.storage
+    #
+    #   bucket = storage.find_bucket "my-bucket"
+    #
+    #   file = bucket.find_file "path/to/my-file.ext"
+    #   file.download "/downloads/#{bucket.name}/#{file.name}"
+    #
     class File
       ##
       # The Connection object.
@@ -31,7 +44,7 @@ module Gcloud
 
       ##
       # Create an empty File object.
-      def initialize
+      def initialize #:nodoc:
         @connection = nil
         @gapi = {}
       end
@@ -118,29 +131,78 @@ module Gcloud
 
       ##
       # Download the file's contents to a local file.
-      # The path provided must be writable.
       #
+      # === Parameters
+      #
+      # +path+::
+      #   The path on the local file system to write the data to.
+      #   The path provided must be writable. (+String+)
+      # +options+::
+      #   An optional Hash for controlling additional behavor. (+Hash+)
+      # +options [:verify]+::
+      #   The verification algoruthm used to ensure the downloaded file contents
+      #   are correct. Default is +:md5+. (+Symbol+)
+      #
+      #   Acceptable values are:
+      #   * +md5+:: Verify file content match using the MD5 hash.
+      #   * +crc32c+:: Verify file content match using the CRC32c hash.
+      #   * +all+:: Perform all available file content verification.
+      #   * +none+:: Don't perform file content verification.
+      #
+      # === Returns
+      #
+      # +::File+ object on the local file system
+      #
+      # === Examples
+      #
+      #   require "glcoud/storage"
+      #
+      #   storage = Gcloud.storage
+      #
+      #   bucket = storage.find_bucket "my-bucket"
+      #
+      #   file = bucket.find_file "path/to/my-file.ext"
       #   file.download "path/to/downloaded/file.ext"
       #
       # The download is verified by calculating the MD5 digest.
       # The CRC32c digest can be used by passing :crc32c.
       #
+      #   require "glcoud/storage"
+      #
+      #   storage = Gcloud.storage
+      #
+      #   bucket = storage.find_bucket "my-bucket"
+      #
+      #   file = bucket.find_file "path/to/my-file.ext"
       #   file.download "path/to/downloaded/file.ext", verify: :crc32c
       #
       # Both the MD5 and CRC32c digest can be used by passing :all.
       #
+      #   require "glcoud/storage"
+      #
+      #   storage = Gcloud.storage
+      #
+      #   bucket = storage.find_bucket "my-bucket"
+      #
+      #   file = bucket.find_file "path/to/my-file.ext"
       #   file.download "path/to/downloaded/file.ext", verify: :all
       #
       # The download verification can be disabled by passing :none
       #
+      #   require "glcoud/storage"
+      #
+      #   storage = Gcloud.storage
+      #
+      #   bucket = storage.find_bucket "my-bucket"
+      #
+      #   file = bucket.find_file "path/to/my-file.ext"
       #   file.download "path/to/downloaded/file.ext", verify: :none
       #
-      # If the verification fails FileVerificationError is raised.
       def download path, options = {}
         ensure_connection!
         resp = connection.download_file bucket, name
         if resp.success?
-          ::File.open path, "w+" do |f|
+          ::File.open path, "wb+" do |f|
             f.write resp.body
           end
           verify_file! ::File.new(path), options
@@ -152,12 +214,63 @@ module Gcloud
       ##
       # Copy the file to a new location.
       #
+      # === Parameters
+      #
+      # +dest_bucket_or_path+::
+      #   Either the bucket to copy the file to, or the path to copy the file to
+      #   in the current bucket. (+String+)
+      # +dest_path+::
+      #   If a bucket was provided in the first parameter, this contains the
+      #   path to copy the file to in the given bucket. (+String+)
+      # +options+::
+      #   An optional Hash for controlling additional behavor. (+Hash+)
+      # +options [:acl]+::
+      #   A predefined set of access controls to apply to new 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
+      #
+      # +File+ object
+      #
+      # === Examples
+      #
+      # The file can also be copied to a new path in the current bucket:
+      #
+      #   require "glcoud/storage"
+      #
+      #   storage = Gcloud.storage
+      #
+      #   bucket = storage.find_bucket "my-bucket"
+      #
+      #   file = bucket.find_file "path/to/my-file.ext"
       #   file.copy "path/to/destination/file.ext"
       #
       # The file can also be copied to a different bucket:
       #
+      #   require "glcoud/storage"
+      #
+      #   storage = Gcloud.storage
+      #
+      #   bucket = storage.find_bucket "my-bucket"
+      #
+      #   file = bucket.find_file "path/to/my-file.ext"
       #   file.copy "new-destination-bucket",
       #             "path/to/destination/file.ext"
+      #
       def copy dest_bucket_or_path, dest_path = nil, options = {}
         ensure_connection!
         dest_bucket, dest_path, options = fix_copy_args dest_bucket_or_path,
@@ -174,6 +287,22 @@ module Gcloud
 
       ##
       # Permenently deletes the file.
+      #
+      # === Returns
+      #
+      # +true+ if the file was deleted.
+      #
+      # === Example
+      #
+      #   require "glcoud/storage"
+      #
+      #   storage = Gcloud.storage
+      #
+      #   bucket = storage.find_bucket "my-bucket"
+      #
+      #   file = bucket.find_file "path/to/my-file.ext"
+      #   file.delete
+      #
       def delete
         ensure_connection!
         resp = connection.delete_file bucket, name
@@ -184,6 +313,54 @@ module Gcloud
         end
       end
 
+      ##
+      # Access without authentication can be granted to a File for a specified
+      # period of time. This URL uses a cryptographic signature
+      # of your credentials to access the file. See the
+      # {Access Control Signed URLs guide
+      # }[https://cloud.google.com/storage/docs/access-control#Signed-URLs]
+      # for more.
+      #
+      # === Parameters
+      #
+      # +options+::
+      #   An optional Hash for controlling additional behavor. (+Hash+)
+      # +options [:method]+::
+      #   The HTTP verb to be used with the signed URL. Signed URLs can be used
+      #   with +GET+, +HEAD+, +PUT+, and +DELETE+ requests. Default is +GET+.
+      #   (+String+)
+      # +options [:expires]+::
+      #   The number of seconds until the URL expires. Default is 300/5 minutes.
+      #   (+Integer+)
+      # +options [:content_type]+::
+      #   When provided, the client (browser) must send this value in the
+      #   HTTP header. e.g. +text/plain+ (+String+)
+      # +options [:content_md5]+::
+      #   The MD5 digest value in base64. If you provide this in the string, the
+      #   client (usually a browser) must provide this HTTP header with this
+      #   same value in its request. (+String+)
+      #
+      # === Examples
+      #
+      #   require "gcloud/storage"
+      #
+      #   storage = Gcloud.storage
+      #
+      #   bucket = storage.find_bucket "my-todo-app"
+      #   file = bucket.find_file "avatars/heidi/400x400.png"
+      #   shared_url = file.signed_url
+      #
+      # Any of the option parameters may be specified:
+      #
+      #   require "gcloud/storage"
+      #
+      #   storage = Gcloud.storage
+      #
+      #   bucket = storage.find_bucket "my-todo-app"
+      #   file = bucket.find_file "avatars/heidi/400x400.png"
+      #   shared_url = file.signed_url method: "GET",
+      #                                expires: 300 # 5 minutes from now
+      #
       def signed_url options = {}
         ensure_connection!
         signer = File::Signer.new self
@@ -191,7 +368,55 @@ module Gcloud
       end
 
       ##
-      # Access Control List
+      # The File::Acl instance used to control access to the file.
+      #
+      # A file 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 file 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"
+      #   file = bucket.find_file "avatars/heidi/400x400.png"
+      #
+      #   email = "heidi@example.net"
+      #   file.acl.add_reader "user-#{email}"
+      #
+      # Access to a file 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"
+      #   file = bucket.find_file "avatars/heidi/400x400.png"
+      #
+      #   email = "authors@example.net"
+      #   file.acl.add_reader "group-#{email}"
+      #
+      # Access to a file can also be granted to a predefined list of
+      # permissions:
+      #
+      #   require "gcloud/storage"
+      #
+      #   storage = Gcloud.storage
+      #
+      #   bucket = storage.find_bucket "my-todo-app"
+      #   file = bucket.find_file "avatars/heidi/400x400.png"
+      #
+      #   file.acl.public!
+      #
       def acl
         @acl ||= File::Acl.new self
       end
@@ -234,7 +459,7 @@ module Gcloud
 
       ##
       # Create a signed_url for a file.
-      class Signer #:nodoc
+      class Signer #:nodoc:
         def initialize file
           @file = file
         end

data/lib/gcloud/storage/file/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,19 @@ module Gcloud
   module Storage
     class File
       ##
+      # = File Access Control List
+      #
       # Represents a File's Access Control List.
+      #
+      #   require "glcoud/storage"
+      #
+      #   storage = Gcloud.storage
+      #
+      #   bucket = storage.find_bucket "my-bucket"
+      #
+      #   file = bucket.find_file "path/to/my-file.ext"
+      #   file.acl.readers.each { |reader| puts reader }
+      #
       class Acl
         RULES = { "authenticatedRead" => "authenticatedRead",
                   "auth" => "authenticatedRead",
@@ -32,7 +45,7 @@ module Gcloud
                   "project_private" => "projectPrivate",
                   "publicRead" => "publicRead",
                   "public" => "publicRead",
-                  "public_read" => "publicRead" }
+                  "public_read" => "publicRead" } #:nodoc:
 
         ##
         # Initialized a new Acl object.
@@ -46,6 +59,20 @@ module Gcloud
           @readers = nil
         end
 
+        ##
+        # Reloads all Access Control List data for the file.
+        #
+        # === Example
+        #
+        #   require "glcoud/storage"
+        #
+        #   storage = Gcloud.storage
+        #
+        #   bucket = storage.find_bucket "my-bucket"
+        #
+        #   file = bucket.find_file "path/to/my-file.ext"
+        #   file.acl.refresh!
+        #
         def refresh!
           resp = @connection.list_file_acls @bucket, @file
           acls = resp.data["items"]
@@ -54,21 +81,127 @@ module Gcloud
           @readers = entities_from_acls acls, "READER"
         end
 
+        ##
+        # Lists the owners of the file.
+        #
+        # === Returns
+        #
+        # Array of Strings
+        #
+        # === Example
+        #
+        #   require "glcoud/storage"
+        #
+        #   storage = Gcloud.storage
+        #
+        #   bucket = storage.find_bucket "my-bucket"
+        #
+        #   file = bucket.find_file "path/to/my-file.ext"
+        #   file.acl.owners.each { |owner| puts owner }
+        #
         def owners
           refresh! if @owners.nil?
           @owners
         end
 
+        ##
+        # Lists the owners of the file.
+        #
+        # === Returns
+        #
+        # Array of Strings
+        #
+        # === Example
+        #
+        #   require "glcoud/storage"
+        #
+        #   storage = Gcloud.storage
+        #
+        #   bucket = storage.find_bucket "my-bucket"
+        #
+        #   file = bucket.find_file "path/to/my-file.ext"
+        #   file.acl.writers.each { |writer| puts writer }
+        #
         def writers
           refresh! if @writers.nil?
           @writers
         end
 
+        ##
+        # Lists the readers of the file.
+        #
+        # === Returns
+        #
+        # Array of Strings
+        #
+        # === Example
+        #
+        #   require "glcoud/storage"
+        #
+        #   storage = Gcloud.storage
+        #
+        #   bucket = storage.find_bucket "my-bucket"
+        #
+        #   file = bucket.find_file "path/to/my-file.ext"
+        #   file.acl.readers.each { |reader| puts reader }
+        #
         def readers
           refresh! if @readers.nil?
           @readers
         end
 
+        ##
+        # Grants owner permission to the file.
+        #
+        # === 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
+        #
+        # +options+::
+        #   An optional Hash for controlling additional behavor. (+Hash+)
+        # +options [:generation]+::
+        #   When present, selects a specific revision of this object.
+        #   Default is the latest version. (+Integer+)
+        #
+        # === Examples
+        #
+        # Access to a file 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"
+        #
+        #   file = bucket.find_file "path/to/my-file.ext"
+        #   email = "heidi@example.net"
+        #   file.acl.add_owner "user-#{email}"
+        #
+        # Access to a file 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"
+        #
+        #   file = bucket.find_file "path/to/my-file.ext"
+        #   email = "authors@example.net"
+        #   file.acl.add_owner "group-#{email}"
+        #
         def add_owner entity, options = {}
           resp = @connection.insert_file_acl @bucket, @file, entity,
                                              "OWNER", options
@@ -80,6 +213,58 @@ module Gcloud
           nil
         end
 
+        ##
+        # Grants writer permission to the file.
+        #
+        # === 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
+        #
+        # +options+::
+        #   An optional Hash for controlling additional behavor. (+Hash+)
+        # +options [:generation]+::
+        #   When present, selects a specific revision of this object.
+        #   Default is the latest version. (+Integer+)
+        #
+        # === Examples
+        #
+        # Access to a file 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"
+        #
+        #   file = bucket.find_file "path/to/my-file.ext"
+        #   email = "heidi@example.net"
+        #   file.acl.add_writer "user-#{email}"
+        #
+        # Access to a file 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"
+        #
+        #   file = bucket.find_file "path/to/my-file.ext"
+        #   email = "authors@example.net"
+        #   file.acl.add_writer "group-#{email}"
+        #
         def add_writer entity, options = {}
           resp = @connection.insert_file_acl @bucket, @file, entity,
                                              "WRITER", options
@@ -91,6 +276,58 @@ module Gcloud
           nil
         end
 
+        ##
+        # Grants reader permission to the file.
+        #
+        # === 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
+        #
+        # +options+::
+        #   An optional Hash for controlling additional behavor. (+Hash+)
+        # +options [:generation]+::
+        #   When present, selects a specific revision of this object.
+        #   Default is the latest version. (+Integer+)
+        #
+        # === Examples
+        #
+        # Access to a file 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"
+        #
+        #   file = bucket.find_file "path/to/my-file.ext"
+        #   email = "heidi@example.net"
+        #   file.acl.add_reader "user-#{email}"
+        #
+        # Access to a file 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"
+        #
+        #   file = bucket.find_file "path/to/my-file.ext"
+        #   email = "authors@example.net"
+        #   file.acl.add_reader "group-#{email}"
+        #
         def add_reader entity, options = {}
           resp = @connection.insert_file_acl @bucket, @file, entity,
                                              "READER", options
@@ -102,6 +339,42 @@ module Gcloud
           nil
         end
 
+        ##
+        # Permenently deletes the entity from the file'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
+        #
+        # +options+::
+        #   An optional Hash for controlling additional behavor. (+Hash+)
+        # +options [:generation]+::
+        #   When present, selects a specific revision of this object.
+        #   Default is the latest version. (+Integer+)
+        #
+        # === Example
+        #
+        #   require "glcoud/storage"
+        #
+        #   storage = Gcloud.storage
+        #
+        #   bucket = storage.find_bucket "my-bucket"
+        #
+        #   file = bucket.find_file "path/to/my-file.ext"
+        #   email = "heidi@example.net"
+        #   file.acl.delete "user-#{email}"
+        #
         def delete entity, options = {}
           resp = @connection.delete_file_acl @bucket, @file, entity, options
           if resp.success?
@@ -113,12 +386,27 @@ 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 file.
+        #
+        # === Example
+        #
+        #   require "glcoud/storage"
+        #
+        #   storage = Gcloud.storage
+        #
+        #   bucket = storage.find_bucket "my-bucket"
+        #
+        #   file = bucket.find_file "path/to/my-file.ext"
+        #   file.acl.auth!
+        #
         def auth!
           update_predefined_acl! "authenticatedRead"
         end
@@ -127,25 +415,100 @@ module Gcloud
         alias_method :authenticated!, :auth!
         alias_method :authenticated_read!, :auth!
 
+        ##
+        # Convenience method to apply the +bucketOwnerFullControl+ predefined
+        # ACL rule to the file.
+        #
+        # === Example
+        #
+        #   require "glcoud/storage"
+        #
+        #   storage = Gcloud.storage
+        #
+        #   bucket = storage.find_bucket "my-bucket"
+        #
+        #   file = bucket.find_file "path/to/my-file.ext"
+        #   file.acl.owner_full!
+        #
         def owner_full!
           update_predefined_acl! "bucketOwnerFullControl"
         end
         alias_method :bucketOwnerFullControl!, :owner_full!
 
+        ##
+        # Convenience method to apply the +bucketOwnerRead+ predefined ACL
+        # rule to the file.
+        #
+        # === Example
+        #
+        #   require "glcoud/storage"
+        #
+        #   storage = Gcloud.storage
+        #
+        #   bucket = storage.find_bucket "my-bucket"
+        #
+        #   file = bucket.find_file "path/to/my-file.ext"
+        #   file.acl.owner_read!
+        #
         def owner_read!
           update_predefined_acl! "bucketOwnerRead"
         end
         alias_method :bucketOwnerRead!, :owner_read!
 
+        ##
+        # Convenience method to apply the +private+ predefined ACL
+        # rule to the file.
+        #
+        # === Example
+        #
+        #   require "glcoud/storage"
+        #
+        #   storage = Gcloud.storage
+        #
+        #   bucket = storage.find_bucket "my-bucket"
+        #
+        #   file = bucket.find_file "path/to/my-file.ext"
+        #   file.acl.private!
+        #
         def private!
           update_predefined_acl! "private"
         end
 
+        ##
+        # Convenience method to apply the +projectPrivate+ predefined ACL
+        # rule to the file.
+        #
+        # === Example
+        #
+        #   require "glcoud/storage"
+        #
+        #   storage = Gcloud.storage
+        #
+        #   bucket = storage.find_bucket "my-bucket"
+        #
+        #   file = bucket.find_file "path/to/my-file.ext"
+        #   file.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 file.
+        #
+        # === Example
+        #
+        #   require "glcoud/storage"
+        #
+        #   storage = Gcloud.storage
+        #
+        #   bucket = storage.find_bucket "my-bucket"
+        #
+        #   file = bucket.find_file "path/to/my-file.ext"
+        #   file.acl.public!
+        #
         def public!
           update_predefined_acl! "publicRead"
         end