gcloud 0.6.3 → 0.7.0

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

@@ -1,4 +1,3 @@
-#--
 # Copyright 2015 Google Inc. All rights reserved.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -13,14 +12,16 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+
 module Gcloud
   module Storage
     class File
       ##
-      # = File Access Control List
+      # # File Access Control List
       #
       # Represents a File's Access Control List.
       #
+      # @example
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
@@ -32,6 +33,7 @@ module Gcloud
       #   file.acl.readers.each { |reader| puts reader }
       #
       class Acl
+        # @private
         RULES = { "authenticatedRead" => "authenticatedRead",
                   "auth" => "authenticatedRead",
                   "auth_read" => "authenticatedRead",
@@ -46,12 +48,12 @@ module Gcloud
                   "project_private" => "projectPrivate",
                   "publicRead" => "publicRead",
                   "public" => "publicRead",
-                  "public_read" => "publicRead" } #:nodoc:
+                  "public_read" => "publicRead" }
 
         ##
-        # Initialized a new Acl object.
+        # @private Initialized a new Acl object.
         # Must provide a valid Bucket object.
-        def initialize file #:nodoc:
+        def initialize file
           @bucket = file.bucket
           @file = file.name
           @connection = file.connection
@@ -63,8 +65,7 @@ module Gcloud
         ##
         # Reloads all Access Control List data for the file.
         #
-        # === Example
-        #
+        # @example
         #   require "gcloud"
         #
         #   gcloud = Gcloud.new
@@ -87,12 +88,9 @@ module Gcloud
         ##
         # Lists the owners of the file.
         #
-        # === Returns
-        #
-        # Array of Strings
-        #
-        # === Example
+        # @return [Array<String>]
         #
+        # @example
         #   require "gcloud"
         #
         #   gcloud = Gcloud.new
@@ -111,12 +109,9 @@ module Gcloud
         ##
         # Lists the owners of the file.
         #
-        # === Returns
-        #
-        # Array of Strings
-        #
-        # === Example
+        # @return [Array<String>]
         #
+        # @example
         #   require "gcloud"
         #
         #   gcloud = Gcloud.new
@@ -135,12 +130,9 @@ module Gcloud
         ##
         # Lists the readers of the file.
         #
-        # === Returns
-        #
-        # Array of Strings
-        #
-        # === Example
+        # @return [Array<String>]
         #
+        # @example
         #   require "gcloud"
         #
         #   gcloud = Gcloud.new
@@ -159,11 +151,8 @@ module Gcloud
         ##
         # Grants owner permission to the file.
         #
-        # === Parameters
-        #
-        # +entity+::
-        #   The entity holding the permission, in one of the following forms:
-        #   (+String+)
+        # @param [String] entity The entity holding the permission, in one of
+        #   the following forms:
         #
         #   * user-userId
         #   * user-email
@@ -174,15 +163,10 @@ module Gcloud
         #   * allUsers
         #   * allAuthenticatedUsers
         #
-        # +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:
+        # @param [Integer] generation When present, selects a specific revision
+        #   of this object. Default is the latest version.
         #
+        # @example Grant access to a user by pre-pending `"user-"` to an email:
         #   require "gcloud"
         #
         #   gcloud = Gcloud.new
@@ -194,9 +178,7 @@ module Gcloud
         #   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:
-        #
+        # @example Grant access to a group by pre-pending `"group-"` to an email
         #   require "gcloud"
         #
         #   gcloud = Gcloud.new
@@ -223,11 +205,8 @@ module Gcloud
         ##
         # Grants writer permission to the file.
         #
-        # === Parameters
-        #
-        # +entity+::
-        #   The entity holding the permission, in one of the following forms:
-        #   (+String+)
+        # @param [String] entity The entity holding the permission, in one of
+        #   the following forms:
         #
         #   * user-userId
         #   * user-email
@@ -238,15 +217,10 @@ module Gcloud
         #   * allUsers
         #   * allAuthenticatedUsers
         #
-        # +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:
+        # @param [Integer] generation When present, selects a specific revision
+        #   of this object. Default is the latest version.
         #
+        # @example Grant access to a user by pre-pending `"user-"` to an email:
         #   require "gcloud"
         #
         #   gcloud = Gcloud.new
@@ -258,9 +232,7 @@ module Gcloud
         #   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:
-        #
+        # @example Grant access to a group by pre-pending `"group-"` to an email
         #   require "gcloud"
         #
         #   gcloud = Gcloud.new
@@ -287,11 +259,8 @@ module Gcloud
         ##
         # Grants reader permission to the file.
         #
-        # === Parameters
-        #
-        # +entity+::
-        #   The entity holding the permission, in one of the following forms:
-        #   (+String+)
+        # @param [String] entity The entity holding the permission, in one of
+        #   the following forms:
         #
         #   * user-userId
         #   * user-email
@@ -302,15 +271,10 @@ module Gcloud
         #   * allUsers
         #   * allAuthenticatedUsers
         #
-        # +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:
+        # @param [Integer] generation When present, selects a specific revision
+        #   of this object. Default is the latest version.
         #
+        # @example Grant access to a user by pre-pending `"user-"` to an email:
         #   require "gcloud"
         #
         #   gcloud = Gcloud.new
@@ -322,9 +286,7 @@ module Gcloud
         #   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:
-        #
+        # @example Grant access to a group by pre-pending `"group-"` to an email
         #   require "gcloud"
         #
         #   gcloud = Gcloud.new
@@ -351,11 +313,8 @@ module Gcloud
         ##
         # Permanently deletes the entity from the file's access control list.
         #
-        # === Parameters
-        #
-        # +entity+::
-        #   The entity holding the permission, in one of the following forms:
-        #   (+String+)
+        # @param [String] entity The entity holding the permission, in one of
+        #   the following forms:
         #
         #   * user-userId
         #   * user-email
@@ -366,12 +325,10 @@ module Gcloud
         #   * allUsers
         #   * allAuthenticatedUsers
         #
-        # +generation+::
-        #   When present, selects a specific revision of this object.
-        #   Default is the latest version. (+Integer+)
-        #
-        # === Example
+        # @param [Integer] generation When present, selects a specific revision
+        #   of this object. Default is the latest version.
         #
+        # @example
         #   require "gcloud"
         #
         #   gcloud = Gcloud.new
@@ -395,18 +352,18 @@ module Gcloud
           false
         end
 
-        def self.predefined_rule_for rule_name #:nodoc:
+        # @private
+        def self.predefined_rule_for rule_name
           RULES[rule_name.to_s]
         end
 
         # Predefined ACL helpers
 
         ##
-        # Convenience method to apply the +authenticatedRead+ predefined ACL
+        # Convenience method to apply the `authenticatedRead` predefined ACL
         # rule to the file.
         #
-        # === Example
-        #
+        # @example
         #   require "gcloud"
         #
         #   gcloud = Gcloud.new
@@ -426,11 +383,10 @@ module Gcloud
         alias_method :authenticated_read!, :auth!
 
         ##
-        # Convenience method to apply the +bucketOwnerFullControl+ predefined
+        # Convenience method to apply the `bucketOwnerFullControl` predefined
         # ACL rule to the file.
         #
-        # === Example
-        #
+        # @example
         #   require "gcloud"
         #
         #   gcloud = Gcloud.new
@@ -447,11 +403,10 @@ module Gcloud
         alias_method :bucketOwnerFullControl!, :owner_full!
 
         ##
-        # Convenience method to apply the +bucketOwnerRead+ predefined ACL
+        # Convenience method to apply the `bucketOwnerRead` predefined ACL
         # rule to the file.
         #
-        # === Example
-        #
+        # @example
         #   require "gcloud"
         #
         #   gcloud = Gcloud.new
@@ -468,11 +423,10 @@ module Gcloud
         alias_method :bucketOwnerRead!, :owner_read!
 
         ##
-        # Convenience method to apply the +private+ predefined ACL
+        # Convenience method to apply the `private` predefined ACL
         # rule to the file.
         #
-        # === Example
-        #
+        # @example
         #   require "gcloud"
         #
         #   gcloud = Gcloud.new
@@ -488,11 +442,10 @@ module Gcloud
         end
 
         ##
-        # Convenience method to apply the +projectPrivate+ predefined ACL
+        # Convenience method to apply the `projectPrivate` predefined ACL
         # rule to the file.
         #
-        # === Example
-        #
+        # @example
         #   require "gcloud"
         #
         #   gcloud = Gcloud.new
@@ -509,11 +462,10 @@ module Gcloud
         alias_method :projectPrivate!, :project_private!
 
         ##
-        # Convenience method to apply the +publicRead+ predefined ACL
+        # Convenience method to apply the `publicRead` predefined ACL
         # rule to the file.
         #
-        # === Example
-        #
+        # @example
         #   require "gcloud"
         #
         #   gcloud = Gcloud.new

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

@@ -1,4 +1,3 @@
-#--
 # Copyright 2015 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 "delegate"
 
 module Gcloud
@@ -40,8 +40,8 @@ module Gcloud
         end
 
         ##
-        # New File::List from a response object.
-        def self.from_response resp, conn #:nodoc:
+        # @private New File::List from a response object.
+        def self.from_response resp, conn
           buckets = Array(resp.data["items"]).map do |gapi_object|
             File.from_gapi gapi_object, conn
           end

data/lib/gcloud/storage/file/verifier.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 "pathname"
 require "digest/md5"
 require "digest/crc32c"
@@ -22,9 +22,10 @@ module Gcloud
   module Storage
     class File
       ##
+      # @private
       # Verifies downloaded files by creating an MD5 or CRC32c hash digest
       # and comparing the value to the one from the Storage API.
-      module Verifier #:nodoc:
+      module Verifier
         def self.verify_md5! gcloud_file, local_file
           gcloud_digest = gcloud_file.md5
           local_digest = md5_for local_file

data/lib/gcloud/storage/project.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/gce"
 require "gcloud/storage/errors"
 require "gcloud/storage/connection"
@@ -24,7 +24,7 @@ require "gcloud/storage/file"
 module Gcloud
   module Storage
     ##
-    # = Project
+    # # Project
     #
     # Represents the project that storage buckets and files belong to.
     # All data in Google Cloud Storage belongs inside a project.
@@ -32,9 +32,12 @@ module Gcloud
     # authentication, and monitoring settings for those APIs.
     #
     # Gcloud::Storage::Project is the main object for interacting with
-    # Google Storage. Gcloud::Storage::Bucket objects are created,
+    # Google Storage. {Gcloud::Storage::Bucket} objects are created,
     # read, updated, and deleted by Gcloud::Storage::Project.
     #
+    # See {Gcloud#storage}
+    #
+    # @example
     #   require "gcloud"
     #
     #   gcloud = Gcloud.new
@@ -43,17 +46,16 @@ module Gcloud
     #   bucket = storage.bucket "my-bucket"
     #   file = bucket.file "path/to/my-file.ext"
     #
-    # See Gcloud#storage
     class Project
       ##
-      # The Connection object.
-      attr_accessor :connection #:nodoc:
+      # @private The Connection object.
+      attr_accessor :connection
 
       ##
-      # Creates a new Project instance.
+      # @private Creates a new Project instance.
       #
-      # See Gcloud#storage
-      def initialize project, credentials #:nodoc:
+      # See {Gcloud#storage}
+      def initialize project, credentials
         project = project.to_s # Always cast to a string
         fail ArgumentError, "project is missing" if project.empty?
         @connection = Connection.new project, credentials
@@ -62,8 +64,7 @@ module Gcloud
       ##
       # The Storage project connected to.
       #
-      # === Example
-      #
+      # @example
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new "my-todo-project",
@@ -77,8 +78,8 @@ module Gcloud
       end
 
       ##
-      # Default project.
-      def self.default_project #:nodoc:
+      # @private Default project.
+      def self.default_project
         ENV["STORAGE_PROJECT"] ||
           ENV["GCLOUD_PROJECT"] ||
           ENV["GOOGLE_CLOUD_PROJECT"] ||
@@ -88,23 +89,16 @@ module Gcloud
       ##
       # Retrieves a list of buckets for the given project.
       #
-      # === Parameters
-      #
-      # +prefix+::
-      #   Filter results to buckets whose names begin with this prefix.
-      #   (+String+)
-      # +token+::
-      #   A previously-returned page token representing part of the larger set
-      #   of results to view. (+String+)
-      # +max+::
-      #   Maximum number of buckets to return. (+Integer+)
-      #
-      # === Returns
-      #
-      # Array of Gcloud::Storage::Bucket (See Gcloud::Storage::Bucket::List)
+      # @param [String] prefix Filter results to buckets whose names begin with
+      #   this prefix.
+      # @param [String] token A previously-returned page token representing part
+      #   of the larger set of results to view.
+      # @param [Integer] max Maximum number of buckets to return.
       #
-      # === Examples
+      # @return [Array<Gcloud::Storage::Bucket>] (See
+      #   {Gcloud::Storage::Bucket::List})
       #
+      # @example
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
@@ -115,9 +109,7 @@ module Gcloud
       #     puts bucket.name
       #   end
       #
-      # You can also retrieve all buckets whose names begin with a prefix using
-      # the +:prefix+ option:
-      #
+      # @example Retrieve all buckets with names that begin with a given prefix:
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
@@ -125,9 +117,7 @@ module Gcloud
       #
       #   user_buckets = storage.buckets prefix: "user-"
       #
-      # If you have a significant number of buckets, you may need to paginate
-      # through them: (See Bucket::List#token)
-      #
+      # @example With pagination: (See {Bucket::List#token})
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
@@ -159,17 +149,12 @@ module Gcloud
       ##
       # Retrieves bucket by name.
       #
-      # === Parameters
-      #
-      # +bucket_name+::
-      #   Name of a bucket. (+String+)
-      #
-      # === Returns
-      #
-      # Gcloud::Storage::Bucket or nil if bucket does not exist
+      # @param [String] bucket_name Name of a bucket.
       #
-      # === Example
+      # @return [Gcloud::Storage::Bucket, nil] Returns nil if bucket does not
+      #   exist
       #
+      # @example
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
@@ -192,101 +177,102 @@ module Gcloud
       ##
       # Creates a new bucket with optional attributes. Also accepts a block for
       # defining the CORS configuration for a static website served from the
-      # bucket. See Bucket::Cors for details. For more information about
-      # configuring buckets as static websites, see {How to Host a Static
-      # Website }[https://cloud.google.com/storage/docs/website-configuration].
-      # For more information about CORS, see {Cross-Origin Resource Sharing
-      # (CORS)}[https://cloud.google.com/storage/docs/cross-origin].
+      # bucket. See {Bucket::Cors} for details.
       #
-      # === Parameters
+      # The API call to create the bucket may be retried under certain
+      # conditions. See {Gcloud::Backoff} to control this behavior, or
+      # specify the wanted behavior in the call with the `:retries:` option.
+      #
+      # You can pass [website
+      # settings](https://cloud.google.com/storage/docs/website-configuration)
+      # for the bucket, including a block that defines CORS rule. See
+      # {Bucket::Cors} for details.
       #
-      # +bucket_name+::
-      #   Name of a bucket. (+String+)
-      # +acl+::
-      #   Apply a predefined set of access controls to this bucket. (+String+)
+      # @see https://cloud.google.com/storage/docs/cross-origin Cross-Origin
+      #   Resource Sharing (CORS)
+      # @see https://cloud.google.com/storage/docs/website-configuration How to
+      #   Host a Static Website
+      #
+      # @param [String] bucket_name Name of a bucket.
+      # @param [String] acl Apply a predefined set of access controls to this
+      #   bucket.
       #
       #   Acceptable values are:
-      #   * +auth+, +auth_read+, +authenticated+, +authenticated_read+,
-      #     +authenticatedRead+ - Project team owners get OWNER access, and
+      #
+      #   * `auth`, `auth_read`, `authenticated`, `authenticated_read`,
+      #     `authenticatedRead` - Project team owners get OWNER access, and
       #     allAuthenticatedUsers get READER access.
-      #   * +private+ - Project team owners get OWNER access.
-      #   * +project_private+, +projectPrivate+ - Project team members get
+      #   * `private` - Project team owners get OWNER access.
+      #   * `project_private`, `projectPrivate` - Project team members get
       #     access according to their roles.
-      #   * +public+, +public_read+, +publicRead+ - Project team owners get
+      #   * `public`, `public_read`, `publicRead` - Project team owners get
       #     OWNER access, and allUsers get READER access.
-      #   * +public_write+, +publicReadWrite+ - Project team owners get OWNER
+      #   * `public_write`, `publicReadWrite` - Project team owners get OWNER
       #     access, and allUsers get WRITER access.
-      # +default_acl+::
-      #   Apply a predefined set of default object access controls to this
-      #   bucket. (+String+)
+      # @param [String] default_acl Apply a predefined set of default object
+      #   access controls to this bucket.
       #
       #   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.
-      # +cors+::
-      #   The CORS rules for the 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].
-      # +location+::
-      #   The location of the bucket. Object data for objects in the bucket
-      #   resides in physical storage within this region. Possible values
-      #   include +ASIA+, +EU+, and +US+.(See the {developer's
-      #   guide}[https://cloud.google.com/storage/docs/bucket-locations] for the
-      #   authoritative list. The default value is +US+. (+String+)
-      # +logging_bucket+::
-      #   The destination bucket for the bucket's logs. For more information,
-      #   see {Access
-      #   Logs}[https://cloud.google.com/storage/docs/access-logs]. (+String+)
-      # +logging_prefix+::
-      #   The prefix 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]
-      #   . 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+)
-      # +retries+::
-      #   The number of times the API call should be retried.
-      #   Default is Gcloud::Backoff.retries. (+Integer+)
-      # +storage_class+::
-      #   Defines how objects in the bucket are stored and determines the SLA
-      #   and the cost of storage. Values include +:standard+, +:nearline+, and
-      #   +:dra+ (Durable Reduced Availability), as well as the strings returned
-      #   by Bucket#storage_class. For more information, see {Storage
-      #   Classes}[https://cloud.google.com/storage/docs/storage-classes].
-      #   The default value is +:standard+. (+Symbol+ or +String+)
-      # +versioning+::
-      #   Whether {Object
-      #   Versioning}[https://cloud.google.com/storage/docs/object-versioning]
-      #   is to be enabled for the bucket. The default value is +false+.
-      #   (+Boolean+)
-      # +website_main+::
-      #   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].
-      # +website_404+::
-      #   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].
-      #
-      # === Returns
-      #
-      # Gcloud::Storage::Bucket
-      #
-      # === Examples
-      #
+      # @param [String] cors The CORS rules for the 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).
+      # @param [String] location The location of the bucket. Object data for
+      #   objects in the bucket resides in physical storage within this region.
+      #   Possible values include `ASIA`, `EU`, and `US`. (See the [developer's
+      #   guide](https://cloud.google.com/storage/docs/bucket-locations) for the
+      #   authoritative list. The default value is `US`.
+      # @param [String] logging_bucket The destination bucket for the bucket's
+      #   logs. For more information, see [Access
+      #   Logs](https://cloud.google.com/storage/docs/access-logs).
+      # @param [String] logging_prefix The prefix 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)
+      #   . 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).
+      # @param [Integer] retries The number of times the API call should be
+      #   retried. Default is {Gcloud::Backoff.retries}.
+      # @param [Symbol, String] storage_class Defines how objects in the bucket
+      #   are stored and determines the SLA and the cost of storage. Values
+      #   include `:standard`, `:nearline`, and `:dra` (Durable Reduced
+      #   Availability), as well as the strings returned by
+      #   Bucket#storage_class. For more information, see [Storage
+      #   Classes](https://cloud.google.com/storage/docs/storage-classes). The
+      #   default value is `:standard`.
+      # @param [Boolean] versioning Whether [Object
+      #   Versioning](https://cloud.google.com/storage/docs/object-versioning)
+      #   is to be enabled for the bucket. The default value is `false`.
+      # @param [String] website_main 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).
+      # @param [String] website_404 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).
+      # @yield [cors] a block for setting CORS rules
+      # @yieldparam [Bucket::Cors] cors the object accepting CORS rules
+      #
+      # @return [Gcloud::Storage::Bucket]
+      #
+      # @example
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
@@ -294,10 +280,7 @@ module Gcloud
       #
       #   bucket = storage.create_bucket "my-bucket"
       #
-      # The API call to create the bucket may be retried under certain
-      # conditions. See Gcloud::Backoff to control this behavior, or
-      # specify the wanted behavior in the call with the +:retries:+ option:
-      #
+      # @example Specify the number of retries to attempt:
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
@@ -305,11 +288,7 @@ module Gcloud
       #
       #   bucket = storage.create_bucket "my-bucket", retries: 5
       #
-      # You can pass {website
-      # settings}[https://cloud.google.com/storage/docs/website-configuration]
-      # for the bucket, including a block that defines CORS rule. See
-      # Bucket::Cors for details.
-      #
+      # @example Add CORS rules in a block:
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new