google-cloud-storage 1.13.1 → 1.14.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2ce659678f9b9f504dd5836bd4985ef9b92f9f6bc41e9ef7919effbed5967ad0
-  data.tar.gz: b4bdce219f6973d4f1ad1ba28501549b0c21ceb2b4fba993ecad37a972b18316
+  metadata.gz: a9f89f223328cb434f1b1f27c38475d5608f83be9b7adb358aa65691d90933ea
+  data.tar.gz: be494fa2f05dd9c00e4d4b0059ca3d654019703f5fadc844b8d3e203163b1e82
 SHA512:
-  metadata.gz: 8ffdeb63b4ecb7aa95644e00ae5d60e244706814e2667314f00448a7cb42b677c4b0ceb8f64bae464984af82108d1fea2953539e77c985e18f381d56251acffe
-  data.tar.gz: 248716f033cdda7a205ed1711585d637be2a8dce3b6f0888e5ad1bb83da28ac06423115e93e7f4f266a4e9c327984c80036d42f87ebbdcdb99dfc0ce6be718a1
+  metadata.gz: d1d7fcfa4de5d70f6dcfd72067cda51a44bbdc74358f54e1a52658965b34b2a6ac15e32c2226fafdf72ccc7f447edecb395f45a50c00c154bb87413aacdbe5a7
+  data.tar.gz: 2d06a35d929cdf7b7909a2407a3cb7886a604e58c58461b427a92c703f1241848df9605810ba957358552ab9069c033d2b14b9b9de27aa4f2814868d5d44ba61

data/.yardopts

@@ -2,7 +2,15 @@
 --title=Google Cloud Storage
 --markup markdown
 --markup-provider redcarpet
+--main OVERVIEW.md
 
 ./lib/**/*.rb
 -
-README.md
+OVERVIEW.md
+AUTHENTICATION.md
+LOGGING.md
+CONTRIBUTING.md
+TROUBLESHOOTING.md
+CHANGELOG.md
+CODE_OF_CONDUCT.md
+LICENSE

data/README.md

@@ -2,7 +2,7 @@
 
 [Google Cloud Storage](https://cloud.google.com/storage/) ([docs](https://cloud.google.com/storage/docs/json_api/)) allows you to store data on Google infrastructure with very high reliability, performance and availability, and can be used to distribute large data objects to users via direct download.
 
-- [google-cloud-storage API documentation](http://googlecloudplatform.github.io/google-cloud-ruby/#/docs/google-cloud-storage/latest)
+- [google-cloud-storage API documentation](http://googlecloudplatform.github.io/google-cloud-ruby/docs/google-cloud-storage/latest)
 - [google-cloud-storage on RubyGems](https://rubygems.org/gems/google-cloud-storage)
 - [Google Cloud Storage documentation](https://cloud.google.com/storage/docs)
 
@@ -16,7 +16,7 @@ $ gem install google-cloud-storage
 
 This library uses Service Account credentials to connect to Google Cloud services. When running on Compute Engine the credentials will be discovered automatically. When running on other environments the Service Account credentials can be specified by providing the path to the JSON file, or the JSON itself, in environment variables.
 
-Instructions and configuration options are covered in the [Authentication Guide](https://googlecloudplatform.github.io/google-cloud-ruby/#/docs/google-cloud-storage/guides/authentication).
+Instructions and configuration options are covered in the [Authentication Guide](https://googlecloudplatform.github.io/google-cloud-ruby/docs/google-cloud-storage/latest/file.AUTHENTICATION).
 
 ## Example
 
@@ -42,7 +42,7 @@ file.copy backup, file.name
 
 ## Enabling Logging
 
-To enable logging for this library, set the logger for the underlying [Google API Client](https://github.com/google/google-api-ruby-client/blob/master/README.md#logging) library. The logger that you set may be a Ruby stdlib [`Logger`](https://ruby-doc.org/stdlib-2.4.0/libdoc/logger/rdoc/Logger.html) as shown below, or a [`Google::Cloud::Logging::Logger`](https://googlecloudplatform.github.io/google-cloud-ruby/#/docs/google-cloud-logging/latest/google/cloud/logging/logger) that will write logs to [Stackdriver Logging](https://cloud.google.com/logging/).
+To enable logging for this library, set the logger for the underlying [Google API Client](https://github.com/google/google-api-ruby-client/blob/master/README.md#logging) library. The logger that you set may be a Ruby stdlib [`Logger`](https://ruby-doc.org/stdlib-2.4.0/libdoc/logger/rdoc/Logger.html) as shown below, or a [`Google::Cloud::Logging::Logger`](https://googlecloudplatform.github.io/google-cloud-ruby/docs/google-cloud-logging/latest/Google/Cloud/Logging/Logger) that will write logs to [Stackdriver Logging](https://cloud.google.com/logging/).
 
 If you do not set the logger explicitly and your application is running in a Rails environment, it will default to `Rails.logger`. Otherwise, if you do not set the logger and you are not using Rails, logging is disabled by default.
 
@@ -63,9 +63,9 @@ Google::Apis.logger = my_logger
 This library is supported on Ruby 2.3+.
 
 Google provides official support for Ruby versions that are actively supported
-by Ruby Core—that is, Ruby versions that are either in normal maintenance or
-in security maintenance, and not end of life. Currently, this means Ruby 2.3
-and later. Older versions of Ruby _may_ still work, but are unsupported and not
+by Ruby Core—that is, Ruby versions that are either in normal maintenance or in
+security maintenance, and not end of life. Currently, this means Ruby 2.3 and
+later. Older versions of Ruby _may_ still work, but are unsupported and not
 recommended. See https://www.ruby-lang.org/en/downloads/branches/ for details
 about the Ruby support schedule.
 
@@ -77,15 +77,24 @@ This library follows [Semantic Versioning](http://semver.org/).
 
 Contributions to this library are always welcome and highly encouraged.
 
-See the [Contributing Guide](https://googlecloudplatform.github.io/google-cloud-ruby/#/docs/guides/contributing) for more information on how to get started.
+See the [Contributing
+Guide](https://googlecloudplatform.github.io/google-cloud-ruby/docs/google-cloud-storage/latest/file.CONTRIBUTING)
+for more information on how to get started.
 
-Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms. See [Code of Conduct](../CODE_OF_CONDUCT.md) for more information.
+Please note that this project is released with a Contributor Code of Conduct. By
+participating in this project you agree to abide by its terms. See [Code of
+Conduct](https://googlecloudplatform.github.io/google-cloud-ruby/docs/google-cloud-storage/latest/file.CODE_OF_CONDUCT)
+for more information.
 
 ## License
 
-This library is licensed under Apache 2.0. Full license text is available in [LICENSE](LICENSE).
+This library is licensed under Apache 2.0. Full license text is available in
+[LICENSE](https://googlecloudplatform.github.io/google-cloud-ruby/docs/google-cloud-storage/latest/file.LICENSE).
 
 ## Support
 
-Please [report bugs at the project on Github](https://github.com/GoogleCloudPlatform/google-cloud-ruby/issues).
-Don't hesitate to [ask questions](http://stackoverflow.com/questions/tagged/google-cloud-platform+ruby) about the client or APIs on [StackOverflow](http://stackoverflow.com).
+Please [report bugs at the project on
+Github](https://github.com/GoogleCloudPlatform/google-cloud-ruby/issues). Don't
+hesitate to [ask
+questions](http://stackoverflow.com/questions/tagged/google-cloud-platform+ruby)
+about the client or APIs on [StackOverflow](http://stackoverflow.com).

data/lib/google-cloud-storage.rb

@@ -29,8 +29,8 @@ module Google
     # Creates a new object for connecting to the Storage service.
     # Each call creates a new connection.
     #
-    # For more information on connecting to Google Cloud see the [Authentication
-    # Guide](https://googlecloudplatform.github.io/google-cloud-ruby/#/docs/guides/authentication).
+    # For more information on connecting to Google Cloud see the
+    # {file:AUTHENTICATION.md Authentication Guide}.
     #
     # @see https://cloud.google.com/storage/docs/authentication#oauth Storage
     #   OAuth 2.0 Authentication
@@ -74,8 +74,8 @@ module Google
     # Creates a new object for connecting to the Storage service.
     # Each call creates a new connection.
     #
-    # For more information on connecting to Google Cloud see the [Authentication
-    # Guide](https://googlecloudplatform.github.io/google-cloud-ruby/#/docs/guides/authentication).
+    # For more information on connecting to Google Cloud see the
+    # {file:AUTHENTICATION.md Authentication Guide}.
     #
     # @param [String] project_id Project identifier for the Storage service
     #   you are connecting to. If not present, the default project for the

data/lib/google/cloud/storage.rb

@@ -29,606 +29,7 @@ module Google
     # networking infrastructure to perform data operations in a cost effective
     # manner.
     #
-    # The goal of google-cloud is to provide an API that is comfortable to
-    # Rubyists. Your authentication credentials are detected automatically in
-    # Google Cloud Platform environments such as Google Compute Engine, Google
-    # App Engine and Google Kubernetes Engine. In other environments you can
-    # configure authentication easily, either directly in your code or via
-    # environment variables. Read more about the options for connecting in the
-    # [Authentication
-    # Guide](https://googlecloudplatform.github.io/google-cloud-ruby/#/docs/guides/authentication).
-    #
-    # ```ruby
-    # require "google/cloud/storage"
-    #
-    # storage = Google::Cloud::Storage.new(
-    #   project_id: "my-project",
-    #   credentials: "/path/to/keyfile.json"
-    # )
-    #
-    # 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](https://googlecloudplatform.github.io/google-cloud-ruby/#/docs/guides/authentication).
-    #
-    # To learn more about Cloud Storage, read the
-    # [Google Cloud Storage Overview
-    # ](https://cloud.google.com/storage/docs/overview).
-    #
-    # ## Enabling Logging
-    #
-    # To enable logging for this library, set the logger for the underlying
-    # [Google API Client](https://github.com/google/google-api-ruby-client/blob/master/README.md#logging)
-    # library. The logger that you set may be a Ruby stdlib
-    # [`Logger`](https://ruby-doc.org/stdlib-2.4.0/libdoc/logger/rdoc/Logger.html)
-    # as shown below, or a
-    # [`Google::Cloud::Logging::Logger`](https://googlecloudplatform.github.io/google-cloud-ruby/#/docs/google-cloud-logging/latest/google/cloud/logging/logger)
-    # that will write logs to [Stackdriver
-    # Logging](https://cloud.google.com/logging/).
-    #
-    # If you do not set the logger explicitly and your application is running in
-    # a Rails environment, it will default to `Rails.logger`. Otherwise, if you
-    # do not set the logger and you are not using Rails, logging is disabled by
-    # default.
-    #
-    # Configuring a Ruby stdlib logger:
-    #
-    # ```ruby
-    # require "logger"
-    #
-    # my_logger = Logger.new $stderr
-    # my_logger.level = Logger::WARN
-    #
-    # # Set the Google API Client logger
-    # Google::Apis.logger = my_logger
-    # ```
-    #
-    # ## Retrieving Buckets
-    #
-    # A {Google::Cloud::Storage::Bucket} instance is a 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.
-    # For more information, see [Working with
-    # Buckets](https://cloud.google.com/storage/docs/creating-buckets).
-    #
-    # Each bucket has a globally unique name, which is how they are retrieved:
-    # (See {Google::Cloud::Storage::Project#bucket})
-    #
-    # ```ruby
-    # require "google/cloud/storage"
-    #
-    # storage = Google::Cloud::Storage.new
-    #
-    # bucket = storage.bucket "my-todo-app"
-    # ```
-    #
-    # You can also retrieve all buckets on a project: (See
-    # {Google::Cloud::Storage::Project#buckets})
-    #
-    # ```ruby
-    # require "google/cloud/storage"
-    #
-    # storage = Google::Cloud::Storage.new
-    #
-    # all_buckets = storage.buckets
-    # ```
-    #
-    # If you have a significant number of buckets, you may need to fetch them
-    # in multiple service requests.
-    #
-    # Iterating over each bucket, potentially with multiple API calls, by
-    # invoking `all` with a block:
-    #
-    # ```ruby
-    # require "google/cloud/storage"
-    #
-    # storage = Google::Cloud::Storage.new
-    #
-    # buckets = storage.buckets
-    # buckets.all do |bucket|
-    #   puts bucket.name
-    # end
-    # ```
-    #
-    # Limiting the number of API calls made:
-    #
-    # ```ruby
-    # require "google/cloud/storage"
-    #
-    # storage = Google::Cloud::Storage.new
-    #
-    # buckets = storage.buckets
-    # buckets.all(request_limit: 10) do |bucket|
-    #   puts bucket.name
-    # end
-    # ```
-    #
-    # See {Google::Cloud::Storage::Bucket::List} for details.
-    #
-    # ## Creating a Bucket
-    #
-    # A unique name is all that is needed to create a new bucket: (See
-    # {Google::Cloud::Storage::Project#create_bucket})
-    #
-    # ```ruby
-    # require "google/cloud/storage"
-    #
-    # storage = Google::Cloud::Storage.new
-    #
-    # bucket = storage.create_bucket "my-todo-app-attachments"
-    # ```
-    #
-    # ## Retrieving Files
-    #
-    # A {Google::Cloud::Storage::File} instance is an individual data object
-    # that you store in Google Cloud Storage. Files contain the data stored as
-    # well as metadata describing the data. Files belong to a bucket and cannot
-    # be shared among buckets. There is no limit on the number of files that
-    # you can create in a bucket. For more information, see [Working with
-    # Objects](https://cloud.google.com/storage/docs/object-basics).
-    #
-    # Files are retrieved by their name, which is the path of the file in the
-    # bucket: (See {Google::Cloud::Storage::Bucket#file})
-    #
-    # ```ruby
-    # require "google/cloud/storage"
-    #
-    # storage = Google::Cloud::Storage.new
-    #
-    # 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)
-    #
-    # ```ruby
-    # require "google/cloud/storage"
-    #
-    # storage = Google::Cloud::Storage.new
-    #
-    # bucket = storage.bucket "my-todo-app"
-    # all_files = bucket.files
-    # ```
-    #
-    # Or you can retrieve all files in a specified path:
-    #
-    # ```ruby
-    # require "google/cloud/storage"
-    #
-    # storage = Google::Cloud::Storage.new
-    #
-    # bucket = storage.bucket "my-todo-app"
-    # avatar_files = bucket.files prefix: "avatars/"
-    # ```
-    #
-    # If you have a significant number of files, you may need to fetch them
-    # in multiple service requests.
-    #
-    # Iterating over each file, potentially with multiple API calls, by
-    # invoking `all` with a block:
-    #
-    # ```ruby
-    # require "google/cloud/storage"
-    #
-    # storage = Google::Cloud::Storage.new
-    # bucket = storage.bucket "my-todo-app"
-    #
-    # files = storage.files
-    # files.all do |file|
-    #   puts file.name
-    # end
-    # ```
-    #
-    # Limiting the number of API calls made:
-    #
-    # ```ruby
-    # require "google/cloud/storage"
-    #
-    # storage = Google::Cloud::Storage.new
-    #
-    # files = storage.files
-    # files.all(request_limit: 10) do |file|
-    #   puts bucket.name
-    # end
-    # ```
-    #
-    # See {Google::Cloud::Storage::File::List} for details.
-    #
-    # ## 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 {Google::Cloud::Storage::Bucket#create_file})
-    #
-    # ```ruby
-    # require "google/cloud/storage"
-    #
-    # storage = Google::Cloud::Storage.new
-    #
-    # bucket = storage.bucket "my-todo-app"
-    # bucket.create_file "/var/todo-app/avatars/heidi/400x400.png",
-    #                    "avatars/heidi/400x400.png"
-    # ```
-    #
-    # Files can also be created from an in-memory StringIO object:
-    #
-    # ```ruby
-    # require "google/cloud/storage"
-    #
-    # storage = Google::Cloud::Storage.new
-    #
-    # bucket = storage.bucket "my-todo-app"
-    # bucket.create_file StringIO.new("Hello world!"), "hello-world.txt"
-    # ```
-    #
-    # ### Customer-supplied encryption keys
-    #
-    # By default, Google Cloud Storage manages server-side encryption keys on
-    # your behalf. However, a [customer-supplied encryption
-    # key](https://cloud.google.com/storage/docs/encryption#customer-supplied)
-    # can be provided with the `encryption_key` option. If given, the same key
-    # must be provided to subsequently download or copy the file. If you use
-    # customer-supplied encryption keys, you must securely manage your keys and
-    # ensure that they are not lost. Also, please note that file metadata is not
-    # encrypted, with the exception of the CRC32C checksum and MD5 hash. The
-    # names of files and buckets are also not encrypted, and you can read or
-    # update the metadata of an encrypted file without providing the encryption
-    # key.
-    #
-    # ```ruby
-    # require "google/cloud/storage"
-    #
-    # storage = Google::Cloud::Storage.new
-    # bucket = storage.bucket "my-todo-app"
-    #
-    # # Key generation shown for example purposes only. Write your own.
-    # cipher = OpenSSL::Cipher.new "aes-256-cfb"
-    # cipher.encrypt
-    # key = cipher.random_key
-    #
-    # bucket.create_file "/var/todo-app/avatars/heidi/400x400.png",
-    #                    "avatars/heidi/400x400.png",
-    #                    encryption_key: key
-    #
-    # # Store your key and hash securely for later use.
-    # file = bucket.file "avatars/heidi/400x400.png",
-    #                    encryption_key: key
-    # ```
-    #
-    # Use {Google::Cloud::Storage::File#rotate} to rotate customer-supplied
-    # encryption keys.
-    #
-    # ```ruby
-    # require "google/cloud/storage"
-    #
-    # storage = Google::Cloud::Storage.new
-    # bucket = storage.bucket "my-todo-app"
-    #
-    # # Old key was stored securely for later use.
-    # old_key = "y\x03\"\x0E\xB6\xD3\x9B\x0E\xAB*\x19\xFAv\xDEY\xBEI..."
-    #
-    # file = bucket.file "path/to/my-file.ext", encryption_key: old_key
-    #
-    # # Key generation shown for example purposes only. Write your own.
-    # cipher = OpenSSL::Cipher.new "aes-256-cfb"
-    # cipher.encrypt
-    # new_key = cipher.random_key
-    #
-    # file.rotate encryption_key: old_key, new_encryption_key: new_key
-    # ```
-    #
-    # ## Downloading a File
-    #
-    # Files can be downloaded to the local file system. (See
-    # {Google::Cloud::Storage::File#download})
-    #
-    # ```ruby
-    # require "google/cloud/storage"
-    #
-    # storage = Google::Cloud::Storage.new
-    #
-    # bucket = storage.bucket "my-todo-app"
-    # file = bucket.file "avatars/heidi/400x400.png"
-    # file.download "/var/todo-app/avatars/heidi/400x400.png"
-    # ```
-    #
-    # Files can also be downloaded to an in-memory StringIO object:
-    #
-    # ```ruby
-    # require "google/cloud/storage"
-    #
-    # storage = Google::Cloud::Storage.new
-    #
-    # bucket = storage.bucket "my-todo-app"
-    # file = bucket.file "hello-world.txt"
-    #
-    # downloaded = file.download
-    # downloaded.rewind
-    # downloaded.read #=> "Hello world!"
-    # ```
-    #
-    # Download a public file with an anonymous, unauthenticated client. Use
-    # `skip_lookup` to avoid errors retrieving non-public bucket and file
-    # metadata.
-    #
-    # ```ruby
-    # require "google/cloud/storage"
-    #
-    # storage = Google::Cloud::Storage.anonymous
-    #
-    # bucket = storage.bucket "public-bucket", skip_lookup: true
-    # file = bucket.file "path/to/public-file.ext", skip_lookup: true
-    #
-    # downloaded = file.download
-    # downloaded.rewind
-    # downloaded.read #=> "Hello world!"
-    # ```
-    #
-    # ## Creating and downloading gzip-encoded files
-    #
-    # When uploading a gzip-compressed file, you should pass
-    # `content_encoding: "gzip"` if you want the file to be eligible for
-    # [decompressive transcoding](https://cloud.google.com/storage/docs/transcoding)
-    # when it is later downloaded. In addition, giving the gzip-compressed file
-    # a name containing the original file extension (for example, `.txt`) will
-    # ensure that the file's `Content-Type` metadata is set correctly. (You can
-    # also set the file's `Content-Type` metadata explicitly with the
-    # `content_type` option.)
-    #
-    # ```ruby
-    # require "zlib"
-    # require "google/cloud/storage"
-    #
-    # storage = Google::Cloud::Storage.new
-    #
-    # gz = StringIO.new ""
-    # z = Zlib::GzipWriter.new gz
-    # z.write "Hello world!"
-    # z.close
-    # data = StringIO.new gz.string
-    #
-    # bucket = storage.bucket "my-bucket"
-    #
-    # bucket.create_file data, "path/to/gzipped.txt",
-    #                    content_encoding: "gzip"
-    #
-    # file = bucket.file "path/to/gzipped.txt"
-    #
-    # # The downloaded data is decompressed by default.
-    # file.download "path/to/downloaded/hello.txt"
-    #
-    # # The downloaded data remains compressed with skip_decompress.
-    # file.download "path/to/downloaded/gzipped.txt",
-    #               skip_decompress: true
-    # ```
-    #
-    # ## 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
-    # {Google::Cloud::Storage::File#signed_url})
-    #
-    # ```ruby
-    # require "google/cloud/storage"
-    #
-    # storage = Google::Cloud::Storage.new
-    #
-    # 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
-    #
-    # Access to a bucket is controlled with
-    # {Google::Cloud::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
-    # email address:
-    #
-    # ```ruby
-    # require "google/cloud/storage"
-    #
-    # storage = Google::Cloud::Storage.new
-    #
-    # bucket = storage.bucket "my-todo-app"
-    #
-    # email = "heidi@example.net"
-    # bucket.acl.add_reader "user-#{email}"
-    # ```
-    #
-    # Access to a bucket can be granted to a group by appending `"group-"` to
-    # the email address:
-    #
-    # ```ruby
-    # require "google/cloud/storage"
-    #
-    # storage = Google::Cloud::Storage.new
-    #
-    # bucket = storage.bucket "my-todo-app"
-    #
-    # email = "authors@example.net"
-    # bucket.acl.add_reader "group-#{email}"
-    # ```
-    #
-    # Access to a bucket can also be granted to a predefined list of
-    # permissions:
-    #
-    # ```ruby
-    # require "google/cloud/storage"
-    #
-    # storage = Google::Cloud::Storage.new
-    #
-    # bucket = storage.bucket "my-todo-app"
-    #
-    # bucket.acl.public!
-    # ```
-    #
-    # ## 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
-    # {Google::Cloud::Storage::Bucket#default_acl}, or by setting permissions to
-    # an individual file with {Google::Cloud::Storage::File#acl}.
-    #
-    # Access to a file can be granted to a user by appending `"user-"` to the
-    # email address:
-    #
-    # ```ruby
-    # require "google/cloud/storage"
-    #
-    # storage = Google::Cloud::Storage.new
-    #
-    # bucket = storage.bucket "my-todo-app"
-    # file = bucket.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:
-    #
-    # ```ruby
-    # require "google/cloud/storage"
-    #
-    # storage = Google::Cloud::Storage.new
-    #
-    # bucket = storage.bucket "my-todo-app"
-    # file = bucket.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:
-    #
-    # ```ruby
-    # require "google/cloud/storage"
-    #
-    # storage = Google::Cloud::Storage.new
-    #
-    # bucket = storage.bucket "my-todo-app"
-    # file = bucket.file "avatars/heidi/400x400.png"
-    #
-    # file.acl.public!
-    # ```
-    #
-    # ## Assigning payment to the requester
-    #
-    # The requester pays feature enables the owner of a bucket to indicate that
-    # a client accessing the bucket or a file it contains must assume the
-    # transit costs related to the access.
-    #
-    # Assign transit costs for bucket and file operations to requesting clients
-    # with the `requester_pays` flag:
-    #
-    # ```ruby
-    # require "google/cloud/storage"
-    #
-    # storage = Google::Cloud::Storage.new
-    #
-    # bucket = storage.bucket "my-bucket"
-    #
-    # bucket.requester_pays = true # API call
-    # # Clients must now provide `user_project` option when calling
-    # # Project#bucket to access this bucket.
-    # ```
-    #
-    # Once the `requester_pays` flag is enabled for a bucket, a client
-    # attempting to access the bucket and its files must provide the
-    # `user_project` option to {Project#bucket}. If the argument given is
-    # `true`, transit costs for operations on the requested bucket or a file it
-    # contains will be billed to the current project for the client. (See
-    # {Project#project} for the ID of the current project.)
-    #
-    # ```ruby
-    # require "google/cloud/storage"
-    #
-    # storage = Google::Cloud::Storage.new
-    #
-    # bucket = storage.bucket "other-project-bucket", user_project: true
-    #
-    # files = bucket.files # Billed to current project
-    # ```
-    #
-    # If the argument is a project ID string, and the indicated project is
-    # authorized for the currently authenticated service account, transit costs
-    # will be billed to the indicated project.
-    #
-    # ```ruby
-    # require "google/cloud/storage"
-    #
-    # storage = Google::Cloud::Storage.new
-    #
-    # bucket = storage.bucket "other-project-bucket",
-    #                         user_project: "my-other-project"
-    # files = bucket.files # Billed to "my-other-project"
-    # ```
-    #
-    # ## Configuring Pub/Sub notification subscriptions
-    #
-    # You can configure notifications to send Google Cloud Pub/Sub messages
-    # about changes to files in your buckets. For example, you can track files
-    # that are created and deleted in your bucket. Each notification contains
-    # information describing both the event that triggered it and the file that
-    # changed.
-    #
-    # You can send notifications to any Cloud Pub/Sub topic in any project for
-    # which your service account has sufficient permissions. As shown below, you
-    # need to explicitly grant permission to your service account to enable
-    # Google Cloud Storage to publish on behalf of your account. (Even if your
-    # current project created and owns the topic.)
-    #
-    # ```ruby
-    # require "google/cloud/pubsub"
-    # require "google/cloud/storage"
-    #
-    # pubsub = Google::Cloud::Pubsub.new
-    # topic = pubsub.create_topic "my-topic"
-    # topic.policy do |p|
-    #   p.add "roles/pubsub.publisher",
-    #         "serviceAccount:my-project" \
-    #         "@gs-project-accounts.iam.gserviceaccount.com"
-    # end
-    #
-    # storage = Google::Cloud::Storage.new
-    # bucket = storage.bucket "my-bucket"
-    #
-    # notification = bucket.create_notification topic.name
-    # ```
-    #
-    # ## Configuring retries and timeout
-    #
-    # You can configure how many times API requests may be automatically
-    # retried. When an API request fails, the response will be inspected to see
-    # if the request meets criteria indicating that it may succeed on retry,
-    # such as `500` and `503` status codes or a specific internal error code
-    # such as `rateLimitExceeded`. If it meets the criteria, the request will be
-    # retried after a delay. If another error occurs, the delay will be
-    # increased before a subsequent attempt, until the `retries` limit is
-    # reached.
-    #
-    # You can also set the request `timeout` value in seconds.
-    #
-    # ```ruby
-    # require "google/cloud/storage"
-    #
-    # storage = Google::Cloud::Storage.new retries: 10, timeout: 120
-    # ```
-    #
-    # See the [Storage status and error
-    # codes](https://cloud.google.com/storage/docs/json_api/v1/status-codes)
-    # for a list of error conditions.
+    # See {file:OVERVIEW.md Storage Overview}.
     #
     module Storage
       ##
@@ -636,8 +37,7 @@ module Google
       # Each call creates a new connection.
       #
       # For more information on connecting to Google Cloud see the
-      # [Authentication
-      # Guide](https://googlecloudplatform.github.io/google-cloud-ruby/#/docs/guides/authentication).
+      # {file:AUTHENTICATION.md Authentication Guide}.
       #
       # @param [String] project_id Project identifier for the Storage service
       #   you are connecting to. If not present, the default project for the