gcloud 0.6.3 → 0.7.0

data/lib/gcloud/storage/bucket.rb

@@ -1,4 +1,3 @@
-#--
 # Copyright 2014 Google Inc. All rights reserved.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -13,6 +12,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+
 require "gcloud/storage/bucket/acl"
 require "gcloud/storage/bucket/list"
 require "gcloud/storage/bucket/cors"
@@ -22,10 +22,11 @@ require "gcloud/upload"
 module Gcloud
   module Storage
     ##
-    # = Bucket
+    # # Bucket
     #
     # Represents a Storage bucket. Belongs to a Project and has many Files.
     #
+    # @example
     #   require "gcloud"
     #
     #   gcloud = Gcloud.new
@@ -36,23 +37,23 @@ module Gcloud
     #
     class Bucket
       ##
-      # The Connection object.
-      attr_accessor :connection #:nodoc:
+      # @private The Connection object.
+      attr_accessor :connection
 
       ##
-      # The Google API Client object.
-      attr_accessor :gapi #:nodoc:
+      # @private The Google API Client object.
+      attr_accessor :gapi
 
       ##
-      # Create an empty Bucket object.
-      def initialize #:nodoc:
+      # @private Create an empty Bucket object.
+      def initialize
         @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
@@ -83,19 +84,22 @@ module Gcloud
 
       ##
       # Returns the current CORS configuration for a static website served from
-      # the bucket. For more information, see {Cross-Origin Resource
-      # Sharing (CORS)}[https://cloud.google.com/storage/docs/cross-origin].
+      # the bucket.
+      #
       # The return value is a frozen (unmodifiable) array of hashes containing
       # the attributes specified for the Bucket resource field
-      # {cors}[https://cloud.google.com/storage/docs/json_api/v1/buckets#cors].
+      # [cors](https://cloud.google.com/storage/docs/json_api/v1/buckets#cors).
       #
       # This method also accepts a block for updating the bucket's CORS rules.
-      # See Bucket::Cors for details.
+      # See {Bucket::Cors} for details.
       #
-      # === Examples
+      # @see https://cloud.google.com/storage/docs/cross-origin Cross-Origin
+      #   Resource Sharing (CORS)
       #
-      # Retrieving the bucket's CORS rules.
+      # @yield [cors] a block for setting CORS rules
+      # @yieldparam [Bucket::Cors] cors the object accepting CORS rules
       #
+      # @example Retrieving the bucket's CORS rules.
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
@@ -107,8 +111,7 @@ module Gcloud
       #               #     "responseHeader"=>["X-My-Custom-Header"],
       #               #     "maxAgeSeconds"=>3600}]
       #
-      # Updating the bucket's CORS rules inside a block.
-      #
+      # @example Updating the bucket's CORS rules inside a block.
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
@@ -135,11 +138,14 @@ module Gcloud
 
       ##
       # Updates the CORS configuration for a static website served from the
-      # bucket. For more information, see {Cross-Origin Resource
-      # Sharing (CORS)}[https://cloud.google.com/storage/docs/cross-origin].
+      # bucket.
+      #
       # Accepts an array of hashes containing the attributes specified for the
-      # {resource description of
-      # cors}[https://cloud.google.com/storage/docs/json_api/v1/buckets#cors].
+      # [resource description of
+      # cors](https://cloud.google.com/storage/docs/json_api/v1/buckets#cors).
+      #
+      # @see https://cloud.google.com/storage/docs/cross-origin Cross-Origin
+      #   Resource Sharing (CORS)
       def cors= new_cors
         patch_gapi! cors: new_cors
       end
@@ -150,29 +156,36 @@ module Gcloud
       # storage within this region. Defaults to US.
       # See the developer's guide for the authoritative list.
       #
-      # https://cloud.google.com/storage/docs/concepts-techniques
+      # @see https://cloud.google.com/storage/docs/concepts-techniques
       def location
         @gapi["location"]
       end
 
       ##
-      # The destination bucket name for the bucket's logs. For more information,
-      # see {Access Logs}[https://cloud.google.com/storage/docs/access-logs].
+      # The destination bucket name for the bucket's logs.
+      #
+      # @see https://cloud.google.com/storage/docs/access-logs Access Logs
+      #
       def logging_bucket
         @gapi["logging"]["logBucket"] if @gapi["logging"]
       end
 
       ##
-      # Updates the destination bucket for the bucket's logs. For more
-      # information, see {Access
-      # Logs}[https://cloud.google.com/storage/docs/access-logs]. (+String+)
+      # Updates the destination bucket for the bucket's logs.
+      #
+      # @see https://cloud.google.com/storage/docs/access-logs Access Logs
+      #
+      # @param [String] logging_bucket The bucket to hold the logging output
+      #
       def logging_bucket= logging_bucket
         patch_gapi! logging_bucket: logging_bucket
       end
 
       ##
       # The logging object prefix for the bucket's logs. For more information,
-      # see {Access Logs}[https://cloud.google.com/storage/docs/access-logs].
+      #
+      # @see https://cloud.google.com/storage/docs/access-logs Access Logs
+      #
       def logging_prefix
         @gapi["logging"]["logObjectPrefix"] if @gapi["logging"]
       end
@@ -180,12 +193,13 @@ module Gcloud
       ##
       # Updates the logging object prefix. This prefix will be used to create
       # log object names for the bucket. It can be at most 900 characters and
-      # must be a {valid object
-      # name}[https://cloud.google.com/storage/docs/bucket-naming#objectnames].
+      # must be a [valid object
+      # name](https://cloud.google.com/storage/docs/bucket-naming#objectnames).
       # By default, the object prefix is the name
-      # of the bucket for which the logs are enabled. For more information, see
-      # {Access Logs}[https://cloud.google.com/storage/docs/access-logs].
-      # (+String+)
+      # of the bucket for which the logs are enabled.
+      #
+      # @see https://cloud.google.com/storage/docs/access-logs Access Logs
+      #
       def logging_prefix= logging_prefix
         patch_gapi! logging_prefix: logging_prefix
       end
@@ -193,74 +207,85 @@ module Gcloud
       ##
       # The bucket's storage class. This defines how objects in the bucket are
       # stored and determines the SLA and the cost of storage. Values include
-      # +STANDARD+, +NEARLINE+, and +DURABLE_REDUCED_AVAILABILITY+.
+      # `STANDARD`, `NEARLINE`, and `DURABLE_REDUCED_AVAILABILITY`.
       def storage_class
         @gapi["storageClass"]
       end
 
       ##
-      # Whether {Object
-      # Versioning}[https://cloud.google.com/storage/docs/object-versioning] is
+      # Whether [Object
+      # Versioning](https://cloud.google.com/storage/docs/object-versioning) is
       # enabled for the bucket.
       def versioning?
         !@gapi["versioning"].nil? && @gapi["versioning"]["enabled"]
       end
 
       ##
-      # Updates whether {Object
-      # Versioning}[https://cloud.google.com/storage/docs/object-versioning] is
-      # enabled for the bucket. (+Boolean+)
+      # Updates whether [Object
+      # Versioning](https://cloud.google.com/storage/docs/object-versioning) is
+      # enabled for the bucket.
+      #
+      # @return [Boolean]
+      #
       def versioning= new_versioning
         patch_gapi! versioning: new_versioning
       end
 
       ##
       # The index page returned from a static website served from the bucket
-      # when a site visitor requests the top level directory. For more
-      # information, see {How to Host a Static Website
-      # }[https://cloud.google.com/storage/docs/website-configuration#step4].
+      # when a site visitor requests the top level directory.
+      #
+      # @see https://cloud.google.com/storage/docs/website-configuration#step4
+      #   How to Host a Static Website
+      #
       def website_main
         @gapi["website"]["mainPageSuffix"] if @gapi["website"]
       end
 
       ##
       # Updates the index page returned from a static website served from the
-      # bucket when a site visitor requests the top level directory. For more
-      # information, see {How to Host a Static Website
-      # }[https://cloud.google.com/storage/docs/website-configuration#step4].
-      # (+String+)
+      # bucket when a site visitor requests the top level directory.
+      #
+      # @see https://cloud.google.com/storage/docs/website-configuration#step4
+      #   How to Host a Static Website
+      #
       def website_main= website_main
         patch_gapi! website_main: website_main
       end
 
       ##
       # The page returned from a static website served from the bucket when a
-      # site visitor requests a resource that does not exist. For more
-      # information, see {How to Host a Static Website
-      # }[https://cloud.google.com/storage/docs/website-configuration#step4].
+      # site visitor requests a resource that does not exist.
+      #
+      # @see https://cloud.google.com/storage/docs/website-configuration#step4
+      #   How to Host a Static Website
+      #
       def website_404
         @gapi["website"]["notFoundPage"] if @gapi["website"]
       end
 
       ##
       # Updates the page returned from a static website served from the bucket
-      # when a site visitor requests a resource that does not exist. For more
-      # information, see {How to Host a Static Website
-      # }[https://cloud.google.com/storage/docs/website-configuration#step4].
-      # (+String+)
+      # when a site visitor requests a resource that does not exist.
+      #
+      # @see https://cloud.google.com/storage/docs/website-configuration#step4
+      #   How to Host a Static Website
+      #
       def website_404= website_404
         patch_gapi! website_404: website_404
       end
 
       ##
       # Updates the bucket with changes made in the given block in a single
-      # PATCH request. The following attributes may be set: #cors=,
-      # #logging_bucket=, #logging_prefix=, #versioning=, #website_main=, and
-      # #website_404=. In addition, the #cors configuration accessible in the
-      # block is completely mutable and will be included in the request.
+      # PATCH request. The following attributes may be set: {#cors=},
+      # {#logging_bucket=}, {#logging_prefix=}, {#versioning=},
+      # {#website_main=}, and {#website_404=}. In addition, the #cors
+      # configuration accessible in the block is completely mutable and will be
+      # included in the request. (See {Bucket::Cors})
       #
-      # === Examples
+      # @yield [bucket] a block yielding a delegate object for updating the file
       #
+      # @example
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
@@ -274,9 +299,7 @@ module Gcloud
       #     b.cors[1]["responseHeader"] << "X-Another-Custom-Header"
       #   end
       #
-      # New CORS rules can also be added in a nested block. See Bucket::Cors for
-      # details.
-      #
+      # @example New CORS rules can also be added in a nested block:
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
@@ -302,18 +325,16 @@ module Gcloud
       # Permanently deletes the bucket.
       # The bucket must be empty before it can be deleted.
       #
-      # === Parameters
-      #
-      # +retries+::
-      #   The number of times the API call should be retried.
-      #   Default is Gcloud::Backoff.retries. (+Integer+)
-      #
-      # === Returns
+      # 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 using the `retries` option.
       #
-      # +true+ if the bucket was deleted.
+      # @param [Integer] retries The number of times the API call should be
+      #   retried. Default is Gcloud::Backoff.retries.
       #
-      # === Examples
+      # @return [Boolean] Returns `true` if the bucket was deleted.
       #
+      # @example
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
@@ -322,10 +343,7 @@ module Gcloud
       #   bucket = storage.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:
-      #
+      # @example Specify the number of retries to attempt:
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
@@ -348,37 +366,28 @@ module Gcloud
       ##
       # Retrieves a list of files matching the criteria.
       #
-      # === Parameters
-      #
-      # +prefix+::
-      #   Filter results to files whose names begin with this prefix.
-      #   (+String+)
-      # +delimiter+::
-      #   Returns results in a directory-like mode. +items+ will contain only
-      #   objects whose names, aside from the +prefix+, do not contain
-      #   +delimiter+. Objects whose names, aside from the +prefix+, contain
-      #   +delimiter+ will have their name, truncated after the +delimiter+,
-      #   returned in +prefixes+. Duplicate +prefixes+ are omitted.
-      # +token+::
-      #   A previously-returned page token representing part of the larger set
-      #   of results to view. (+String+)
-      # +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+)
-      # +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+)
-      #
-      # === Returns
-      #
-      # Array of Gcloud::Storage::File (See Gcloud::Storage::File::List)
-      #
-      # === Examples
-      #
+      # @param [String] prefix Filter results to files whose names begin with
+      #   this prefix.
+      # @param [String] delimiter Returns results in a directory-like mode.
+      #   `items` will contain only objects whose names, aside from the
+      #   `prefix`, do not contain `delimiter`. Objects whose names, aside from
+      #   the `prefix`, contain `delimiter` will have their name, truncated
+      #   after the `delimiter`, returned in `prefixes`. Duplicate `prefixes`
+      #   are omitted.
+      # @param [String] token A previously-returned page token representing part
+      #   of the larger set of results to view.
+      # @param [Integer] 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.
+      # @param [Boolean] 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).
+      #
+      # @return [Array<Gcloud::Storage::File>] (See
+      #   {Gcloud::Storage::File::List})
+      #
+      # @example
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
@@ -390,9 +399,7 @@ module Gcloud
       #     puts file.name
       #   end
       #
-      # If you have a significant number of files, you may need to paginate
-      # through them: (See File::List#token)
-      #
+      # @example With pagination: (See {File::List#token})
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
@@ -433,20 +440,13 @@ module Gcloud
       ##
       # Retrieves a file matching the path.
       #
-      # === Parameters
-      #
-      # +path+::
-      #   Name (path) of the file. (+String+)
-      # +generation+::
-      #   When present, selects a specific revision of this object.
-      #   Default is the latest version. (+Integer+)
-      #
-      # === Returns
+      # @param [String] path Name (path) of the file.
+      # @param [Integer] generation When present, selects a specific revision of
+      #   this object. Default is the latest version.
       #
-      # Gcloud::Storage::File or nil if file does not exist
-      #
-      # === Example
+      # @return [Gcloud::Storage::File, nil] Returns nil if file does not exist
       #
+      # @example
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
@@ -473,73 +473,68 @@ module Gcloud
       # 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
+      # A `chunk_size` value can be provided in the options to be used
+      # in resumable uploads. This value is the number of bytes per
+      # chunk and must be divisible by 256KB. If it is not divisible
+      # by 256KB then it will be lowered to the nearest acceptable
+      # value.
       #
-      # +file+::
-      #   Path of the file on the filesystem to upload. (+String+)
-      # +path+::
-      #   Path to store the file in Google Cloud Storage. (+String+)
-      # +acl+::
-      #   A predefined set of access controls to apply to this file.
-      #   (+String+)
+      # @param [String] file Path of the file on the filesystem to upload.
+      # @param [String] path Path to store the file in Google Cloud Storage.
+      # @param [String] acl A predefined set of access controls to apply to this
+      #   file.
       #
       #   Acceptable values are:
-      #   * +auth+, +auth_read+, +authenticated+, +authenticated_read+,
-      #     +authenticatedRead+ - File owner gets OWNER access, and
+      #
+      #   * `auth`, `auth_read`, `authenticated`, `authenticated_read`,
+      #     `authenticatedRead` - File owner gets OWNER access, and
       #     allAuthenticatedUsers get READER access.
-      #   * +owner_full+, +bucketOwnerFullControl+ - File owner gets OWNER
+      #   * `owner_full`, `bucketOwnerFullControl` - File owner gets OWNER
       #     access, and project team owners get OWNER access.
-      #   * +owner_read+, +bucketOwnerRead+ - File owner gets OWNER access, and
+      #   * `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,
+      #   * `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
+      #   * `public`, `public_read`, `publicRead` - File owner gets OWNER
       #     access, and allUsers get READER access.
-      # +cache_control+::
-      #   The {Cache-Control}[https://tools.ietf.org/html/rfc7234#section-5.2]
-      #   response header to be returned when the file is downloaded. (+String+)
-      # +content_disposition+::
-      #   The {Content-Disposition}[https://tools.ietf.org/html/rfc6266]
-      #   response header to be returned when the file is downloaded. (+String+)
-      # +content_encoding+::
-      #   The {Content-Encoding
-      #   }[https://tools.ietf.org/html/rfc7231#section-3.1.2.2] response header
-      #   to be returned when the file is downloaded. (+String+)
-      # +content_language+::
-      #   The {Content-Language}[http://tools.ietf.org/html/bcp47] response
-      #   header to be returned when the file is downloaded. (+String+)
-      # +content_type+::
-      #   The {Content-Type}[https://tools.ietf.org/html/rfc2616#section-14.17]
-      #   response header to be returned when the file is downloaded. (+String+)
-      # +chunk_size+::
-      #   The number of bytes per chunk in a resumable upload. Must be divisible
-      #   by 256KB. If it is not divisible by 265KB then it will be lowered to
-      #   the nearest acceptable value. (+Integer+)
-      # +crc32c+::
-      #   The CRC32c checksum of the file data, as described in
-      #   {RFC 4960, Appendix B}[http://tools.ietf.org/html/rfc4960#appendix-B].
+      # @param [String] cache_control The
+      #   [Cache-Control](https://tools.ietf.org/html/rfc7234#section-5.2)
+      #   response header to be returned when the file is downloaded.
+      # @param [String] content_disposition The
+      #   [Content-Disposition](https://tools.ietf.org/html/rfc6266)
+      #   response header to be returned when the file is downloaded.
+      # @param [String] content_encoding The [Content-Encoding
+      #   ](https://tools.ietf.org/html/rfc7231#section-3.1.2.2) response header
+      #   to be returned when the file is downloaded.
+      # @param [String] content_language The
+      #   [Content-Language](http://tools.ietf.org/html/bcp47) response
+      #   header to be returned when the file is downloaded.
+      # @param [String] content_type The
+      #   [Content-Type](https://tools.ietf.org/html/rfc2616#section-14.17)
+      #   response header to be returned when the file is downloaded.
+      # @param [Integer] chunk_size The number of bytes per chunk in a resumable
+      #   upload. Must be divisible by 256KB. If it is not divisible by 265KB
+      #   then it will be lowered to the nearest acceptable value.
+      # @param [String] crc32c The CRC32c checksum of the file data, as
+      #   described in [RFC 4960, Appendix
+      #   B](http://tools.ietf.org/html/rfc4960#appendix-B).
       #   If provided, Cloud Storage will only create the file if the value
       #   matches the value calculated by the service. See
-      #   {Validation}[https://cloud.google.com/storage/docs/hashes-etags]
-      #   for more information. (+String+)
-      # +md5+::
-      #   The MD5 hash of the file data. If provided, Cloud Storage will only
-      #   create the file if the value matches the value calculated by the
-      #   service. See
-      #   {Validation}[https://cloud.google.com/storage/docs/hashes-etags]
-      #   for more information. (+String+)
-      # +metadata+::
-      #   A hash of custom, user-provided web-safe keys and arbitrary string
-      #   values that will returned with requests for the file as "x-goog-meta-"
-      #   response headers. (+Hash+)
-      #
-      # === Returns
-      #
-      # Gcloud::Storage::File
-      #
-      # === Examples
-      #
+      #   [Validation](https://cloud.google.com/storage/docs/hashes-etags)
+      #   for more information.
+      # @param [String] md5 The MD5 hash of the file data. If provided, Cloud
+      #   Storage will only create the file if the value matches the value
+      #   calculated by the service. See
+      #   [Validation](https://cloud.google.com/storage/docs/hashes-etags) for
+      #   more information.
+      # @param [Hash] metadata A hash of custom, user-provided web-safe keys and
+      #   arbitrary string values that will returned with requests for the file
+      #   as "x-goog-meta-" response headers.
+      #
+      # @return [Gcloud::Storage::File]
+      #
+      # @example
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
@@ -549,8 +544,7 @@ module Gcloud
       #
       #   bucket.create_file "path/to/local.file.ext"
       #
-      # Additionally, a destination path can be specified.
-      #
+      # @example Additionally, a destination path can be specified.
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
@@ -561,12 +555,7 @@ module Gcloud
       #   bucket.create_file "path/to/local.file.ext",
       #                      "destination/path/file.ext"
       #
-      # A +chunk_size+ value can be provided in the options to be used
-      # in resumable uploads. This value is the number of bytes per
-      # chunk and must be divisible by 256KB. If it is not divisible
-      # by 265KB then it will be lowered to the nearest acceptable
-      # value.
-      #
+      # @example Specify the chunk size as a number of bytes:
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
@@ -578,29 +567,30 @@ module Gcloud
       #                      "destination/path/file.ext",
       #                      chunk_size: 1024*1024 # 1 MB chunk
       #
-      # ==== Troubleshooting large uploads
+      # #### Troubleshooting large uploads
       #
       # You may encounter errors while attempting to upload large files. Below
       # are a couple of common cases and their solutions.
       #
-      # ===== Handling memory errors
+      # ##### Handling memory errors
       #
-      # If you encounter a memory error such as +NoMemoryError+, try performing
-      # a resumable upload and setting the +chunk_size+ option to a value that
+      # If you encounter a memory error such as `NoMemoryError`, try performing
+      # a resumable upload and setting the `chunk_size` option to a value that
       # works for your environment, as explained in the final example above.
       #
-      # ===== Handling broken pipe errors
+      # ##### Handling broken pipe errors
       #
-      # To avoid broken pipe (+Errno::EPIPE+) errors when uploading, add the
-      # {httpclient}[https://rubygems.org/gems/httpclient] gem to your project,
+      # To avoid broken pipe (`Errno::EPIPE`) errors when uploading, add the
+      # [httpclient](https://rubygems.org/gems/httpclient) gem to your project,
       # and the configuration shown below. These lines must execute after you
       # require gcloud but before you make your first gcloud connection. The
-      # first statement configures {Faraday}[https://rubygems.org/gems/faraday]
+      # first statement configures [Faraday](https://rubygems.org/gems/faraday)
       # to use httpclient. The second statement, which should only be added if
       # you are using a version of Faraday at or above 0.9.2, is a workaround
-      # for {this gzip
-      # issue}[https://github.com/GoogleCloudPlatform/gcloud-ruby/issues/367].
+      # for [this gzip
+      # issue](https://github.com/GoogleCloudPlatform/gcloud-ruby/issues/367).
       #
+      # @example
       #   require "gcloud"
       #
       #   # Use httpclient to avoid broken pipe errors with large uploads
@@ -639,16 +629,12 @@ module Gcloud
       #
       # 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.
+      # many predefined lists.
       #
-      # === Examples
-      #
-      # Access to a bucket can be granted to a user by appending +"user-"+ to
-      # the email address:
+      # @see https://cloud.google.com/storage/docs/access-control Access Control
+      #   guide
       #
+      # @example Grant access to a user by pre-pending `"user-"` to an email:
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
@@ -659,9 +645,7 @@ module Gcloud
       #   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:
-      #
+      # @example Grant access to a group by pre-pending `"group-"` to an email:
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
@@ -672,9 +656,7 @@ module Gcloud
       #   email = "authors@example.net"
       #   bucket.acl.add_reader "group-#{email}"
       #
-      # Access to a bucket can also be granted to a predefined list of
-      # permissions:
-      #
+      # @example Or, grant access via a predefined permissions list:
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
@@ -694,16 +676,12 @@ module Gcloud
       #
       # 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
+      # as well as many predefined lists.
       #
-      # Access to a bucket's files can be granted to a user by appending
-      # +"user-"+ to the email address:
+      # @see https://cloud.google.com/storage/docs/access-control Access Control
+      #   guide
       #
+      # @example Grant access to a user by pre-pending `"user-"` to an email:
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
@@ -714,9 +692,7 @@ module Gcloud
       #   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:
-      #
+      # @example Grant access to a group by pre-pending `"group-"` to an email
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
@@ -727,9 +703,7 @@ module Gcloud
       #   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:
-      #
+      # @example Or, grant access via a predefined permissions list:
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
@@ -738,6 +712,7 @@ module Gcloud
       #   bucket = storage.bucket "my-todo-app"
       #
       #   bucket.default_acl.public!
+      #
       def default_acl
         @default_acl ||= Bucket::DefaultAcl.new self
       end
@@ -756,8 +731,8 @@ module Gcloud
       alias_method :refresh!, :reload!
 
       ##
-      # New Bucket from a Google API Client object.
-      def self.from_gapi gapi, conn #:nodoc:
+      # @private New Bucket from a Google API Client object.
+      def self.from_gapi gapi, conn
         new.tap do |f|
           f.gapi = gapi
           f.connection = conn
@@ -790,8 +765,8 @@ module Gcloud
       end
 
       ##
-      # Determines if a resumable upload should be used.
-      def resumable_upload? file #:nodoc:
+      # @private Determines if a resumable upload should be used.
+      def resumable_upload? file
         ::File.size?(file).to_i > Upload.resumable_threshold
       end