gcloud 0.6.3 → 0.7.0

data/lib/gcloud/search/index/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.
 
+
 module Gcloud
   module Search
     class Index
@@ -25,7 +25,7 @@ module Gcloud
         attr_accessor :token
 
         ##
-        # Create a new Index::List with an array of Index instances.
+        # Create a new Index::List with an array of {Index} instances.
         def initialize arr = []
           super arr
         end
@@ -50,7 +50,7 @@ module Gcloud
         end
 
         ##
-        # Retrieves all indexes by repeatedly loading pages until #next?
+        # Retrieves all indexes by repeatedly loading pages until {#next?}
         # returns false. Returns the list instance for method chaining.
         def all
           while next?
@@ -62,8 +62,8 @@ module Gcloud
         end
 
         ##
-        # New Indexs::List from a response object.
-        def self.from_response resp, conn #:nodoc:
+        # @private New Index::List from a response object.
+        def self.from_response resp, conn
           data = JSON.parse resp.body
           indexes = new(Array(data["indexes"]).map do |raw_index|
             Index.from_raw raw_index, conn

data/lib/gcloud/search/project.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 "gcloud/gce"
 require "gcloud/search/connection"
 require "gcloud/search/credentials"
@@ -22,31 +22,31 @@ require "gcloud/search/errors"
 module Gcloud
   module Search
     ##
-    # = Project
+    # # Project
     #
     # Projects are top-level containers in Google Cloud Platform. They store
     # information about billing and authorized users, and they control access to
     # Google Cloud Search resources. Each project has a friendly name and a
-    # unique ID. Projects can be created only in the {Google Developers
-    # Console}[https://console.developers.google.com].
+    # unique ID. Projects can be created only in the [Google Developers
+    # Console](https://console.developers.google.com). See {Gcloud#search}.
     #
+    # @example
     #   require "gcloud"
     #
     #   gcloud = Gcloud.new
     #   search = gcloud.search
     #   index = search.index "books"
     #
-    # See Gcloud#search
     class Project
       ##
-      # The Connection object.
-      attr_accessor :connection #:nodoc:
+      # @private The Connection object.
+      attr_accessor :connection
 
       ##
-      # Creates a new Connection instance.
+      # @private Creates a new Connection instance.
       #
       # See Gcloud.search
-      def initialize project, credentials #:nodoc:
+      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
@@ -55,8 +55,9 @@ module Gcloud
       ##
       # The ID of the current project.
       #
-      # === Example
+      # @return [String]
       #
+      # @example
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new "my-project", "/path/to/keyfile.json"
@@ -69,8 +70,8 @@ module Gcloud
       end
 
       ##
-      # Default project.
-      def self.default_project #:nodoc:
+      # @private Default project.
+      def self.default_project
         ENV["SEARCH_PROJECT"] ||
           ENV["GCLOUD_PROJECT"] ||
           ENV["GOOGLE_CLOUD_PROJECT"] ||
@@ -80,22 +81,15 @@ module Gcloud
       ##
       # Retrieves an existing index by ID.
       #
-      # === Parameters
-      #
-      # +index_id+::
-      #   The ID of an index. (+String+)
-      # +skip_lookup+::
-      #   Optionally create an Index object without verifying the index resource
-      #   exists on the Search service. Documents saved on this object will
-      #   create the index resource if the resource does not yet exist. Default
-      #   is +false+. (+Boolean+)
-      #
-      # === Returns
+      # @param [String] index_id The ID of an index.
+      # @param [Boolean] skip_lookup Optionally create an Index object without
+      #   verifying the index resource exists on the Search service. Documents
+      #   saved on this object will create the index resource if the resource
+      #   does not yet exist. Default is `false`.
       #
-      # Gcloud::Search::Index or nil if the index does not exist
-      #
-      # === Examples
+      # @return [Gcloud::Search::Index, nil] nil if the index does not exist
       #
+      # @example
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
@@ -104,9 +98,7 @@ module Gcloud
       #   index = search.index "books"
       #   index.index_id #=> "books"
       #
-      # A new index can be created by providing the desired +index_id+ and the
-      # +skip_lookup+ option:
-      #
+      # @example A new index can be created with `index_id` and `skip_lookup`:
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
@@ -130,23 +122,17 @@ module Gcloud
       ##
       # Retrieves the list of indexes belonging to the project.
       #
-      # === Parameters
+      # @param [String] prefix The prefix of the index name. It is used to list
+      #   all indexes with names that have 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 indexes to return. The default is
+      #   `100`.
       #
-      # +prefix+::
-      #   The prefix of the index name. It is used to list all indexes with
-      #   names that have this prefix. (+String+)
-      # +token+::
-      #   A previously-returned page token representing part of the larger set
-      #   of results to view. (+String+)
-      # +max+::
-      #   Maximum number of indexes to return. The default is +100+. (+Integer+)
-      #
-      # === Returns
-      #
-      # Array of Gcloud::Search::Index (See Gcloud::Search::Index::List)
-      #
-      # === Examples
+      # @return [Array<Gcloud::Search::Index>] (See
+      #   {Gcloud::Search::Index::List})
       #
+      # @example
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
@@ -157,9 +143,7 @@ module Gcloud
       #     puts index.index_id
       #   end
       #
-      # If you have a significant number of indexes, you may need to paginate
-      # through them: (See Gcloud::Search::Index::List)
-      #
+      # @example Using pagination: (See {Gcloud::Search::Index::List})
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new

data/lib/gcloud/search/result.rb

@@ -1,4 +1,3 @@
-#--
 # Copyright 2015 Google Inc. All rights reserved.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -13,31 +12,36 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+
 require "gcloud/search/result/list"
 require "gcloud/search/fields"
 
 module Gcloud
   module Search
     ##
-    # = Result
+    # # Result
     #
-    # See Gcloud#search
+    # See {Gcloud#search}
     class Result
       ##
-      # Creates a new Result instance.
-      def initialize #:nodoc:
+      # @private Creates a new Result instance.
+      def initialize
         @fields = Fields.new
         @raw = {}
       end
 
       ##
       # The unique identifier of the document referenced in the search result.
+      #
+      # @return [String]
       def doc_id
         @raw["docId"]
       end
 
       ##
       # The token for the next page of results.
+      #
+      # @return [String]
       def token
         @raw["nextPageToken"]
       end
@@ -45,18 +49,12 @@ module Gcloud
       ##
       # Retrieve the field values associated to a field name.
       #
-      # === Parameters
-      #
-      # +name+::
-      #   The name of the field. New values will be configured with this name.
-      #   (+String+)
-      #
-      # === Returns
+      # @param [String] name The name of the field. New values will be
+      #   configured with this name.
       #
-      # FieldValue
-      #
-      # === Example
+      # @return [FieldValue]
       #
+      # @example
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
@@ -74,26 +72,21 @@ module Gcloud
         @fields[name]
       end
 
-      # rubocop:disable Style/TrivialAccessors
-      # Disable rubocop because we want .fields to be listed with the other
-      # methods on the class.
+      # Trivial accessor because we want .fields to be listed with methods.
 
       ##
       # The fields in the search result. Each field has a name (String) and a
-      # list of values (FieldValues). (See Fields)
+      # list of values ({FieldValues}). (See {Fields})
       def fields
         @fields
       end
 
-      # rubocop:enable Style/TrivialAccessors
-
       ##
       # Calls block once for each field, passing the field name and values pair
       # as parameters. If no block is given an enumerator is returned instead.
-      # (See Fields#each)
-      #
-      # === Example
+      # (See {Fields#each})
       #
+      # @example
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
@@ -116,8 +109,11 @@ module Gcloud
 
       ##
       # Returns a new array populated with all the field names.
-      # (See Fields#names)
+      # (See {Fields#names})
+      #
+      # @return [Array<String>]
       #
+      # @example
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
@@ -136,8 +132,8 @@ module Gcloud
       end
 
       ##
-      # Override to keep working in interactive shells manageable.
-      def inspect #:nodoc:
+      # @private Override to keep working in interactive shells manageable.
+      def inspect
         insp_token = ""
         if token
           trunc_token = "#{token[0, 8]}...#{token[-5..-1]}"
@@ -149,8 +145,8 @@ module Gcloud
       end
 
       ##
-      # New Result from a raw data object.
-      def self.from_hash hash #:nodoc:
+      # @private New Result from a raw data object.
+      def self.from_hash hash
         result = new
         result.instance_variable_set "@raw", hash
         result.instance_variable_set "@fields", Fields.from_raw(hash["fields"])
@@ -158,8 +154,8 @@ module Gcloud
       end
 
       ##
-      # Returns the Result data as a hash
-      def to_hash #:nodoc:
+      # @private Returns the Result data as a hash
+      def to_hash
         hash = @raw.dup
         hash["fields"] = @fields.to_raw
         hash

data/lib/gcloud/search/result/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.
 
+
 module Gcloud
   module Search
     class Result
@@ -28,11 +28,11 @@ module Gcloud
         # The number of documents that match the query. It is greater than or
         # equal to the number of documents actually returned. This is an
         # approximation and not an exact count unless it is less than or equal
-        # to the Index#search +matched_count_accuracy+ option.
+        # to the {Index#search} `matched_count_accuracy` option.
         attr_reader :matched_count
 
         ##
-        # Create a new Result::List with an array of Result instances.
+        # Create a new Result::List with an array of {Result} instances.
         def initialize arr = []
           super arr
         end
@@ -52,7 +52,7 @@ module Gcloud
         end
 
         ##
-        # Retrieves all results by repeatedly loading pages until #next?
+        # Retrieves all results by repeatedly loading pages until {#next?}
         # returns false. Returns the list instance for method chaining.
         def all
           while next?
@@ -64,8 +64,8 @@ module Gcloud
         end
 
         ##
-        # New Result::List from a response object.
-        def self.from_response resp, index, query, search_options #:nodoc:
+        # @private New Result::List from a response object.
+        def self.from_response resp, index, query, search_options
           data = JSON.parse resp.body
           results = new(Array(data["results"]).map do |raw|
             Result.from_hash raw

data/lib/gcloud/storage.rb

@@ -1,4 +1,3 @@
-#--
 # Copyright 2014 Google Inc. All rights reserved.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -13,40 +12,34 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+
 require "gcloud"
 require "gcloud/storage/project"
 
-#--
-# Google Cloud Storage
 module Gcloud
   ##
   # Creates a new object for connecting to the Storage service.
   # Each call creates a new connection.
   #
-  # === Parameters
+  # For more information on connecting to Google Cloud see the [Authentication
+  # Guide](https://googlecloudplatform.github.io/gcloud-ruby/#/docs/guides/authentication).
   #
-  # +project+::
-  #   Project identifier for the Storage service you are connecting to.
-  #   (+String+)
-  # +keyfile+::
-  #   Keyfile downloaded from Google Cloud. If file path the file must be
-  #   readable. (+String+ or +Hash+)
-  # +scope+::
-  #   The OAuth 2.0 scopes controlling the set of resources and operations that
-  #   the connection can access. See {Using OAuth 2.0 to Access Google
-  #   APIs}[https://developers.google.com/identity/protocols/OAuth2]. (+String+
-  #   or +Array+)
+  # @param [String] project Project identifier for the Storage service you are
+  #   connecting to.
+  # @param [String, Hash] keyfile Keyfile downloaded from Google Cloud. If file
+  #   path the file must be readable.
+  # @param [String, Array<String>] scope The OAuth 2.0 scopes controlling the
+  #   set of resources and operations that the connection can access. See [Using
+  #   OAuth 2.0 to Access Google
+  #   APIs](https://developers.google.com/identity/protocols/OAuth2).
   #
   #   The default scope is:
   #
-  #   * +https://www.googleapis.com/auth/devstorage.full_control+
-  #
-  # === Returns
+  #   * `https://www.googleapis.com/auth/devstorage.full_control`
   #
-  # Gcloud::Storage::Project
-  #
-  # === Example
+  # @return [Gcloud::Storage::Project]
   #
+  # @example
   #   require "gcloud/storage"
   #
   #   storage = Gcloud.storage "my-todo-project",
@@ -66,7 +59,7 @@ module Gcloud
   end
 
   ##
-  # = Google Cloud Storage
+  # # Google Cloud Storage
   #
   # Google Cloud Storage is an Internet service to store data in Google's cloud.
   # It allows world-wide storage and retrieval of any amount of data and at any
@@ -74,83 +67,95 @@ module Gcloud
   # infrastructure to perform data operations in a cost effective manner.
   #
   # Gcloud's goal is to provide a API that is familiar and comfortable to
-  # Rubyists. Authentication is handled by Gcloud#storage. You can provide the
+  # Rubyists. Authentication is handled by {Gcloud#storage}. You can provide the
   # project and credential information to connect to the Storage service, or if
   # you are running on Google Compute Engine this configuration is taken care
   # of for you.
   #
-  #   require "gcloud"
+  # ```ruby
+  # require "gcloud"
   #
-  #   gcloud = Gcloud.new "my-todo-project",
-  #                       "/path/to/keyfile.json"
-  #   storage = gcloud.storage
+  # gcloud = Gcloud.new "my-todo-project",
+  #                     "/path/to/keyfile.json"
+  # storage = gcloud.storage
   #
-  #   bucket = storage.bucket "my-bucket"
-  #   file = bucket.file "path/to/my-file.ext"
+  # bucket = storage.bucket "my-bucket"
+  # file = bucket.file "path/to/my-file.ext"
+  # ```
   #
   # You can learn more about various options for connection on the
-  # {Authentication Guide}[link:AUTHENTICATION.md].
+  # [Authentication
+  # Guide](https://googlecloudplatform.github.io/gcloud-ruby/#/docs/guides/authentication).
   #
   # To learn more about Cloud Storage, read the
-  # {Google Cloud Storage Overview
-  # }[https://cloud.google.com/storage/docs/overview].
+  # [Google Cloud Storage Overview
+  # ](https://cloud.google.com/storage/docs/overview).
   #
-  # == Retrieving Buckets
+  # ## Retrieving Buckets
   #
   # A Bucket is the container for your data. There is no limit on the number of
   # buckets that you can create in a project. You can use buckets to organize
   # and control access to your data. Each bucket has a unique name, which is how
-  # they are retrieved: (See Project#bucket)
+  # they are retrieved: (See {Gcloud::Storage::Project#bucket})
   #
-  #   require "gcloud"
+  # ```ruby
+  # require "gcloud"
   #
-  #   gcloud = Gcloud.new
-  #   storage = gcloud.storage
+  # gcloud = Gcloud.new
+  # storage = gcloud.storage
   #
-  #   bucket = storage.bucket "my-todo-app"
+  # bucket = storage.bucket "my-todo-app"
+  # ```
   #
-  # You can also retrieve all buckets on a project: (See Project#buckets)
+  # You can also retrieve all buckets on a project: (See
+  # {Gcloud::Storage::Project#buckets})
   #
-  #   require "gcloud"
+  # ```ruby
+  # require "gcloud"
   #
-  #   gcloud = Gcloud.new
-  #   storage = gcloud.storage
+  # gcloud = Gcloud.new
+  # storage = gcloud.storage
   #
-  #   all_buckets = storage.buckets
+  # all_buckets = storage.buckets
+  # ```
   #
   # If you have a significant number of buckets, you may need to paginate
-  # through them: (See Bucket::List#token)
-  #
-  #   require "gcloud"
-  #
-  #   gcloud = Gcloud.new
-  #   storage = gcloud.storage
-  #
-  #   all_buckets = []
-  #   tmp_buckets = storage.buckets
-  #   while tmp_buckets.any? do
-  #     tmp_buckets.each do |bucket|
-  #       all_buckets << bucket
-  #     end
-  #     # break loop if no more buckets available
-  #     break if tmp_buckets.token.nil?
-  #     # get the next group of buckets
-  #     tmp_buckets = storage.buckets token: tmp_buckets.token
+  # through them: (See {Gcloud::Storage::Bucket::List#token})
+  #
+  # ```ruby
+  # require "gcloud"
+  #
+  # gcloud = Gcloud.new
+  # storage = gcloud.storage
+  #
+  # all_buckets = []
+  # tmp_buckets = storage.buckets
+  # while tmp_buckets.any? do
+  #   tmp_buckets.each do |bucket|
+  #     all_buckets << bucket
   #   end
+  #   # break loop if no more buckets available
+  #   break if tmp_buckets.token.nil?
+  #   # get the next group of buckets
+  #   tmp_buckets = storage.buckets token: tmp_buckets.token
+  # end
+  # ```
   #
-  # == Creating a Bucket
+  # ## Creating a Bucket
   #
-  # A unique name is all that is needed to create a new bucket:
-  # (See Project#create_bucket)
+  # A unique name is all that is needed to create a new bucket: (See
+  # {Gcloud::Storage::Project#create_bucket})
   #
-  #   require "gcloud"
+  # ```ruby
+  # require "gcloud"
   #
-  #   gcloud = Gcloud.new
-  #   storage = gcloud.storage
+  # gcloud = Gcloud.new
+  # storage = gcloud.storage
   #
-  #   bucket = storage.create_bucket "my-todo-app-attachments"
+  # bucket = storage.create_bucket "my-todo-app-attachments"
+  # ```
   #
-  # == Retrieving Files
+  # ## Retrieving Files
   #
   # A File is an individual pieces of data that you store in Google Cloud
   # Storage. Files contain the data stored as well as metadata describing the
@@ -158,218 +163,247 @@ module Gcloud
   # no limit on the number of objects that you can create in a bucket.
   #
   # Files are retrieved by their name, which is the path of the file in the
-  # bucket: (See Bucket#file)
+  # bucket: (See {Gcloud::Storage::Bucket#file})
   #
-  #   require "gcloud"
+  # ```ruby
+  # require "gcloud"
   #
-  #   gcloud = Gcloud.new
-  #   storage = gcloud.storage
+  # gcloud = Gcloud.new
+  # storage = gcloud.storage
   #
-  #   bucket = storage.bucket "my-todo-app"
-  #   file = bucket.file "avatars/heidi/400x400.png"
+  # bucket = storage.bucket "my-todo-app"
+  # file = bucket.file "avatars/heidi/400x400.png"
+  # ```
   #
   # You can also retrieve all files in a bucket: (See Bucket#files)
   #
-  #   require "gcloud"
+  # ```ruby
+  # require "gcloud"
   #
-  #   gcloud = Gcloud.new
-  #   storage = gcloud.storage
+  # gcloud = Gcloud.new
+  # storage = gcloud.storage
   #
-  #   bucket = storage.bucket "my-todo-app"
-  #   all_files = bucket.files
+  # bucket = storage.bucket "my-todo-app"
+  # all_files = bucket.files
+  # ```
   #
   # Or you can retrieve all files in a specified path:
   #
-  #   require "gcloud"
+  # ```ruby
+  # require "gcloud"
   #
-  #   gcloud = Gcloud.new
-  #   storage = gcloud.storage
+  # gcloud = Gcloud.new
+  # storage = gcloud.storage
   #
-  #   bucket = storage.bucket "my-todo-app"
-  #   avatar_files = bucket.files prefix: "avatars/"
+  # bucket = storage.bucket "my-todo-app"
+  # avatar_files = bucket.files prefix: "avatars/"
+  # ```
   #
   # If you have a significant number of files, you may need to paginate through
-  # them: (See File::List#token)
+  # them: (See {Gcloud::Storage::File::List#token})
   #
-  #   require "gcloud"
+  # ```ruby
+  # require "gcloud"
   #
-  #   gcloud = Gcloud.new
-  #   storage = gcloud.storage
+  # gcloud = Gcloud.new
+  # storage = gcloud.storage
   #
-  #   bucket = storage.bucket "my-todo-app"
+  # bucket = storage.bucket "my-todo-app"
   #
-  #   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 files available
-  #     break if tmp_files.token.nil?
-  #     # get the next group of files
-  #     tmp_files = bucket.files token: tmp_files.token
+  # 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 files available
+  #   break if tmp_files.token.nil?
+  #   # get the next group of files
+  #   tmp_files = bucket.files token: tmp_files.token
+  # end
+  # ```
   #
-  # == Creating a File
+  # ## Creating a File
   #
   # A new File can be uploaded by specifying the location of a file on the local
   # file system, and the name/path that the file should be stored in the bucket.
-  # (See Bucket#create_file)
+  # (See {Gcloud::Storage::Bucket#create_file})
   #
-  #   require "gcloud"
+  # ```ruby
+  # require "gcloud"
   #
-  #   gcloud = Gcloud.new
-  #   storage = gcloud.storage
+  # gcloud = Gcloud.new
+  # storage = gcloud.storage
   #
-  #   bucket = storage.bucket "my-todo-app"
-  #   bucket.create_file "/var/todo-app/avatars/heidi/400x400.png",
-  #                      "avatars/heidi/400x400.png"
+  # bucket = storage.bucket "my-todo-app"
+  # bucket.create_file "/var/todo-app/avatars/heidi/400x400.png",
+  #                    "avatars/heidi/400x400.png"
+  # ```
   #
-  # === A note about large uploads
+  # ### A note about large uploads
   #
   # You may encounter a Broken pipe (Errno::EPIPE) error when attempting to
   # upload large files. To avoid this problem, add the
-  # {httpclient}[https://rubygems.org/gems/httpclient] gem to your project, and
+  # [httpclient](https://rubygems.org/gems/httpclient) gem to your project, and
   # the line (or lines) of 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]
+  # The 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].
+  # 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).
   #
-  #   require "gcloud"
+  # ```ruby
+  # require "gcloud"
   #
-  #   # Use httpclient to avoid broken pipe errors with large uploads
-  #   Faraday.default_adapter = :httpclient
+  # # Use httpclient to avoid broken pipe errors with large uploads
+  # Faraday.default_adapter = :httpclient
   #
-  #   # Only add the following statement if using Faraday >= 0.9.2
-  #   # Override gzip middleware with no-op for httpclient
-  #   Faraday::Response.register_middleware :gzip =>
-  #                                           Faraday::Response::Middleware
+  # # Only add the following statement if using Faraday >= 0.9.2
+  # # Override gzip middleware with no-op for httpclient
+  # Faraday::Response.register_middleware :gzip =>
+  #                                         Faraday::Response::Middleware
   #
-  #   gcloud = Gcloud.new
-  #   storage = gcloud.storage
+  # gcloud = Gcloud.new
+  # storage = gcloud.storage
+  # ```
   #
-  # == Downloading a File
+  # ## Downloading a File
   #
-  # Files can be downloaded to the local file system. (See File#download)
+  # Files can be downloaded to the local file system. (See
+  # {Gcloud::Storage::File#download})
   #
-  #   require "gcloud"
+  # ```ruby
+  # require "gcloud"
   #
-  #   gcloud = Gcloud.new
-  #   storage = gcloud.storage
+  # gcloud = Gcloud.new
+  # storage = gcloud.storage
   #
-  #   bucket = storage.bucket "my-todo-app"
-  #   file = bucket.file "avatars/heidi/400x400.png"
-  #   file.download "/var/todo-app/avatars/heidi/400x400.png"
+  # bucket = storage.bucket "my-todo-app"
+  # file = bucket.file "avatars/heidi/400x400.png"
+  # file.download "/var/todo-app/avatars/heidi/400x400.png"
+  # ```
   #
-  # == Using Signed URLs
+  # ## Using Signed URLs
   #
   # 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 File#signed_url)
+  # period of time. This URL uses a cryptographic signature of your credentials
+  # to access the file. (See {Gcloud::Storage::File#signed_url})
   #
-  #   require "gcloud"
+  # ```ruby
+  # require "gcloud"
   #
-  #   gcloud = Gcloud.new
-  #   storage = gcloud.storage
+  # gcloud = Gcloud.new
+  # storage = gcloud.storage
   #
-  #   bucket = storage.bucket "my-todo-app"
-  #   file = bucket.file "avatars/heidi/400x400.png"
-  #   shared_url = file.signed_url method: "GET",
-  #                                expires: 300 # 5 minutes from now
+  # bucket = storage.bucket "my-todo-app"
+  # file = bucket.file "avatars/heidi/400x400.png"
+  # shared_url = file.signed_url method: "GET",
+  #                              expires: 300 # 5 minutes from now
+  # ```
   #
-  # == Controlling Access to a Bucket
+  # ## Controlling Access to a Bucket
   #
-  # Access to a bucket is controlled with Bucket#acl. 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.
+  # Access to a bucket is controlled with {Gcloud::Storage::Bucket#acl}. 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.
   #
-  # Access to a bucket can be granted to a user by appending +"user-"+ to the
+  # Access to a bucket can be granted to a user by appending `"user-"` to the
   # email address:
   #
-  #   require "gcloud"
+  # ```ruby
+  # require "gcloud"
   #
-  #   gcloud = Gcloud.new
-  #   storage = gcloud.storage
+  # gcloud = Gcloud.new
+  # storage = gcloud.storage
   #
-  #   bucket = storage.bucket "my-todo-app"
+  # bucket = storage.bucket "my-todo-app"
   #
-  #   email = "heidi@example.net"
-  #   bucket.acl.add_reader "user-#{email}"
+  # 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
+  # Access to a bucket can be granted to a group by appending `"group-"` to the
   # email address:
   #
-  #   require "gcloud"
+  # ```ruby
+  # require "gcloud"
   #
-  #   gcloud = Gcloud.new
-  #   storage = gcloud.storage
+  # gcloud = Gcloud.new
+  # storage = gcloud.storage
   #
-  #   bucket = storage.bucket "my-todo-app"
+  # bucket = storage.bucket "my-todo-app"
   #
-  #   email = "authors@example.net"
-  #   bucket.acl.add_reader "group-#{email}"
+  # 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"
+  # ```ruby
+  # require "gcloud"
   #
-  #   gcloud = Gcloud.new
-  #   storage = gcloud.storage
+  # gcloud = Gcloud.new
+  # storage = gcloud.storage
   #
-  #   bucket = storage.bucket "my-todo-app"
+  # bucket = storage.bucket "my-todo-app"
   #
-  #   bucket.acl.public!
+  # bucket.acl.public!
+  # ```
   #
-  # == Controlling Access to a File
+  # ## Controlling Access to a File
   #
   # Access to a file is controlled in two ways, either by the setting the
-  # default permissions to all files in a bucket with Bucket#default_acl, or by
-  # setting permissions to an individual file with File#acl.
+  # default permissions to all files in a bucket with
+  # {Gcloud::Storage::Bucket#default_acl}, or by setting permissions to an
+  # individual file with {Gcloud::Storage::File#acl}.
   #
-  # Access to a file can be granted to a user by appending +"user-"+ to the
+  # Access to a file can be granted to a user by appending `"user-"` to the
   # email address:
   #
-  #   require "gcloud"
+  # ```ruby
+  # require "gcloud"
   #
-  #   gcloud = Gcloud.new
-  #   storage = gcloud.storage
+  # gcloud = Gcloud.new
+  # storage = gcloud.storage
   #
-  #   bucket = storage.bucket "my-todo-app"
-  #   file = bucket.file "avatars/heidi/400x400.png"
+  # bucket = storage.bucket "my-todo-app"
+  # file = bucket.file "avatars/heidi/400x400.png"
   #
-  #   email = "heidi@example.net"
-  #   file.acl.add_reader "user-#{email}"
+  # 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
+  # Access to a file can be granted to a group by appending `"group-"` to the
   # email address:
   #
-  #   require "gcloud"
+  # ```ruby
+  # require "gcloud"
   #
-  #   gcloud = Gcloud.new
-  #   storage = gcloud.storage
+  # gcloud = Gcloud.new
+  # storage = gcloud.storage
   #
-  #   bucket = storage.bucket "my-todo-app"
-  #   file = bucket.file "avatars/heidi/400x400.png"
+  # bucket = storage.bucket "my-todo-app"
+  # file = bucket.file "avatars/heidi/400x400.png"
   #
-  #   email = "authors@example.net"
-  #   file.acl.add_reader "group-#{email}"
+  # 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"
+  # ```ruby
+  # require "gcloud"
   #
-  #   gcloud = Gcloud.new
-  #   storage = gcloud.storage
+  # gcloud = Gcloud.new
+  # storage = gcloud.storage
   #
-  #   bucket = storage.bucket "my-todo-app"
-  #   file = bucket.file "avatars/heidi/400x400.png"
+  # bucket = storage.bucket "my-todo-app"
+  # file = bucket.file "avatars/heidi/400x400.png"
   #
-  #   file.acl.public!
+  # file.acl.public!
+  # ```
   #
   module Storage
   end