google-cloud-storage 0.20.2 → 0.21.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: dacd357f4e4020c18e891b3cf1952236b612f95f
-  data.tar.gz: b3add45394ea994cb45a84cd9f9da8d4e28daf81
+  metadata.gz: 94a9b4984ad82c331f96b286defb5fe25cebce12
+  data.tar.gz: 7ed68558c6cb0db8cd0b431657607219482aa056
 SHA512:
-  metadata.gz: fb5b20e2f5e6e07ddc10dbb582209c783404072fa98107e69bbc4af4eb5c93fdbd7e5bc080c54feb6e2c8ac812e1d27dd39233e80e116962f7852acaaea9a0d8
-  data.tar.gz: 6426d6e45323407820f5bfacc9e8f03fdd7fa5eb6f7a425f683d06c78991272dc824641cec7e01423895aeeb25a998f759d97fb6d26022bf0bcd1c49562bb072
+  metadata.gz: 4361659e81aebc49a2c29e3ac77339835a1e893b0e4ea9029a08b3aa88f9a9313b2e75eadb54c4d6bca6ec2a68dafe99b967d89d7c99361768f48e45d187aad9
+  data.tar.gz: be19d2b6af46f535269f98d7aee9ca3145fd2b7a61d1a8e65529e758aebbb09231a2931b04c2a68f19737cef7171f19b207324543f9add28342827880b76052c

data/lib/google-cloud-storage.rb

@@ -105,20 +105,9 @@ module Google
     def self.storage project = nil, keyfile = nil, scope: nil, retries: nil,
                      timeout: nil
       require "google/cloud/storage"
-      project ||= Google::Cloud::Storage::Project.default_project
-      project = project.to_s # Always cast to a string
-      fail ArgumentError, "project is missing" if project.empty?
-
-      if keyfile.nil?
-        credentials = Google::Cloud::Storage::Credentials.default scope: scope
-      else
-        credentials = Google::Cloud::Storage::Credentials.new(
-          keyfile, scope: scope)
-      end
-
-      Google::Cloud::Storage::Project.new(
-        Google::Cloud::Storage::Service.new(
-          project, credentials, retries: retries, timeout: timeout))
+      Google::Cloud::Storage.new project: project, keyfile: keyfile,
+                                 scope: scope, retries: retries,
+                                 timeout: timeout
     end
   end
 end

data/lib/google/cloud/storage.rb

@@ -34,11 +34,12 @@ module Google
     # is taken care of for you.
     #
     # ```ruby
-    # require "google/cloud"
+    # require "google/cloud/storage"
     #
-    # gcloud = Google::Cloud.new "my-todo-project",
-    #                     "/path/to/keyfile.json"
-    # storage = gcloud.storage
+    # storage = Google::Cloud::Storage.new(
+    #   project: "my-todo-project",
+    #   keyfile: "/path/to/keyfile.json"
+    # )
     #
     # bucket = storage.bucket "my-bucket"
     # file = bucket.file "path/to/my-file.ext"
@@ -61,10 +62,9 @@ module Google
     # {Google::Cloud::Storage::Project#bucket})
     #
     # ```ruby
-    # require "google/cloud"
+    # require "google/cloud/storage"
     #
-    # gcloud = Google::Cloud.new
-    # storage = gcloud.storage
+    # storage = Google::Cloud::Storage.new
     #
     # bucket = storage.bucket "my-todo-app"
     # ```
@@ -73,10 +73,9 @@ module Google
     # {Google::Cloud::Storage::Project#buckets})
     #
     # ```ruby
-    # require "google/cloud"
+    # require "google/cloud/storage"
     #
-    # gcloud = Google::Cloud.new
-    # storage = gcloud.storage
+    # storage = Google::Cloud::Storage.new
     #
     # all_buckets = storage.buckets
     # ```
@@ -85,10 +84,9 @@ module Google
     # through them: (See {Google::Cloud::Storage::Bucket::List#token})
     #
     # ```ruby
-    # require "google/cloud"
+    # require "google/cloud/storage"
     #
-    # gcloud = Google::Cloud.new
-    # storage = gcloud.storage
+    # storage = Google::Cloud::Storage.new
     #
     # all_buckets = []
     # tmp_buckets = storage.buckets
@@ -109,10 +107,9 @@ module Google
     # {Google::Cloud::Storage::Project#create_bucket})
     #
     # ```ruby
-    # require "google/cloud"
+    # require "google/cloud/storage"
     #
-    # gcloud = Google::Cloud.new
-    # storage = gcloud.storage
+    # storage = Google::Cloud::Storage.new
     #
     # bucket = storage.create_bucket "my-todo-app-attachments"
     # ```
@@ -128,10 +125,9 @@ module Google
     # bucket: (See {Google::Cloud::Storage::Bucket#file})
     #
     # ```ruby
-    # require "google/cloud"
+    # require "google/cloud/storage"
     #
-    # gcloud = Google::Cloud.new
-    # storage = gcloud.storage
+    # storage = Google::Cloud::Storage.new
     #
     # bucket = storage.bucket "my-todo-app"
     # file = bucket.file "avatars/heidi/400x400.png"
@@ -140,10 +136,9 @@ module Google
     # You can also retrieve all files in a bucket: (See Bucket#files)
     #
     # ```ruby
-    # require "google/cloud"
+    # require "google/cloud/storage"
     #
-    # gcloud = Google::Cloud.new
-    # storage = gcloud.storage
+    # storage = Google::Cloud::Storage.new
     #
     # bucket = storage.bucket "my-todo-app"
     # all_files = bucket.files
@@ -152,10 +147,9 @@ module Google
     # Or you can retrieve all files in a specified path:
     #
     # ```ruby
-    # require "google/cloud"
+    # require "google/cloud/storage"
     #
-    # gcloud = Google::Cloud.new
-    # storage = gcloud.storage
+    # storage = Google::Cloud::Storage.new
     #
     # bucket = storage.bucket "my-todo-app"
     # avatar_files = bucket.files prefix: "avatars/"
@@ -165,10 +159,9 @@ module Google
     # through them: (See {Google::Cloud::Storage::File::List#token})
     #
     # ```ruby
-    # require "google/cloud"
+    # require "google/cloud/storage"
     #
-    # gcloud = Google::Cloud.new
-    # storage = gcloud.storage
+    # storage = Google::Cloud::Storage.new
     #
     # bucket = storage.bucket "my-todo-app"
     #
@@ -192,10 +185,9 @@ module Google
     # bucket. (See {Google::Cloud::Storage::Bucket#create_file})
     #
     # ```ruby
-    # require "google/cloud"
+    # require "google/cloud/storage"
     #
-    # gcloud = Google::Cloud.new
-    # storage = gcloud.storage
+    # storage = Google::Cloud::Storage.new
     #
     # bucket = storage.bucket "my-todo-app"
     # bucket.create_file "/var/todo-app/avatars/heidi/400x400.png",
@@ -217,11 +209,10 @@ module Google
     # an encrypted file without providing the encryption key.
     #
     # ```ruby
-    # require "google/cloud"
+    # require "google/cloud/storage"
     # require "digest/sha2"
     #
-    # gcloud = Google::Cloud.new
-    # storage = gcloud.storage
+    # storage = Google::Cloud::Storage.new
     # bucket = storage.bucket "my-todo-app"
     #
     # # Key generation shown for example purposes only. Write your own.
@@ -247,10 +238,9 @@ module Google
     # {Google::Cloud::Storage::File#download})
     #
     # ```ruby
-    # require "google/cloud"
+    # require "google/cloud/storage"
     #
-    # gcloud = Google::Cloud.new
-    # storage = gcloud.storage
+    # storage = Google::Cloud::Storage.new
     #
     # bucket = storage.bucket "my-todo-app"
     # file = bucket.file "avatars/heidi/400x400.png"
@@ -265,10 +255,9 @@ module Google
     # {Google::Cloud::Storage::File#signed_url})
     #
     # ```ruby
-    # require "google/cloud"
+    # require "google/cloud/storage"
     #
-    # gcloud = Google::Cloud.new
-    # storage = gcloud.storage
+    # storage = Google::Cloud::Storage.new
     #
     # bucket = storage.bucket "my-todo-app"
     # file = bucket.file "avatars/heidi/400x400.png"
@@ -289,10 +278,9 @@ module Google
     # email address:
     #
     # ```ruby
-    # require "google/cloud"
+    # require "google/cloud/storage"
     #
-    # gcloud = Google::Cloud.new
-    # storage = gcloud.storage
+    # storage = Google::Cloud::Storage.new
     #
     # bucket = storage.bucket "my-todo-app"
     #
@@ -304,10 +292,9 @@ module Google
     # the email address:
     #
     # ```ruby
-    # require "google/cloud"
+    # require "google/cloud/storage"
     #
-    # gcloud = Google::Cloud.new
-    # storage = gcloud.storage
+    # storage = Google::Cloud::Storage.new
     #
     # bucket = storage.bucket "my-todo-app"
     #
@@ -319,10 +306,9 @@ module Google
     # permissions:
     #
     # ```ruby
-    # require "google/cloud"
+    # require "google/cloud/storage"
     #
-    # gcloud = Google::Cloud.new
-    # storage = gcloud.storage
+    # storage = Google::Cloud::Storage.new
     #
     # bucket = storage.bucket "my-todo-app"
     #
@@ -340,10 +326,9 @@ module Google
     # email address:
     #
     # ```ruby
-    # require "google/cloud"
+    # require "google/cloud/storage"
     #
-    # gcloud = Google::Cloud.new
-    # storage = gcloud.storage
+    # storage = Google::Cloud::Storage.new
     #
     # bucket = storage.bucket "my-todo-app"
     # file = bucket.file "avatars/heidi/400x400.png"
@@ -356,10 +341,9 @@ module Google
     # email address:
     #
     # ```ruby
-    # require "google/cloud"
+    # require "google/cloud/storage"
     #
-    # gcloud = Google::Cloud.new
-    # storage = gcloud.storage
+    # storage = Google::Cloud::Storage.new
     #
     # bucket = storage.bucket "my-todo-app"
     # file = bucket.file "avatars/heidi/400x400.png"
@@ -371,10 +355,9 @@ module Google
     # Access to a file can also be granted to a predefined list of permissions:
     #
     # ```ruby
-    # require "google/cloud"
+    # require "google/cloud/storage"
     #
-    # gcloud = Google::Cloud.new
-    # storage = gcloud.storage
+    # storage = Google::Cloud::Storage.new
     #
     # bucket = storage.bucket "my-todo-app"
     # file = bucket.file "avatars/heidi/400x400.png"
@@ -396,10 +379,9 @@ module Google
     # You can also set the request `timeout` value in seconds.
     #
     # ```ruby
-    # require "google/cloud"
+    # require "google/cloud/storage"
     #
-    # gcloud = Google::Cloud.new
-    # storage = gcloud.storage retries: 10, timeout: 120
+    # storage = Google::Cloud::Storage.new retries: 10, timeout: 120
     # ```
     #
     # See the [Storage status and error
@@ -407,6 +389,60 @@ module Google
     # for a list of error conditions.
     #
     module Storage
+      ##
+      # 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).
+      #
+      # @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`
+      # @param [Integer] retries Number of times to retry requests on server
+      #   error. The default value is `3`. Optional.
+      # @param [Integer] timeout Default timeout to use in requests. Optional.
+      #
+      # @return [Google::Cloud::Storage::Project]
+      #
+      # @example
+      #   require "google/cloud/storage"
+      #
+      #   storage = Google::Cloud::Storage.new(
+      #     project: "my-todo-project",
+      #     keyfile: "/path/to/keyfile.json"
+      #   )
+      #
+      #   bucket = storage.bucket "my-bucket"
+      #   file = bucket.file "path/to/my-file.ext"
+      #
+      def self.new project: nil, keyfile: nil, scope: nil, retries: nil,
+                   timeout: nil
+        project ||= Google::Cloud::Storage::Project.default_project
+        project = project.to_s # Always cast to a string
+        fail ArgumentError, "project is missing" if project.empty?
+
+        if keyfile.nil?
+          credentials = Google::Cloud::Storage::Credentials.default scope: scope
+        else
+          credentials = Google::Cloud::Storage::Credentials.new(
+            keyfile, scope: scope)
+        end
+
+        Google::Cloud::Storage::Project.new(
+          Google::Cloud::Storage::Service.new(
+            project, credentials, retries: retries, timeout: timeout))
+      end
     end
   end
 end

data/lib/google/cloud/storage/bucket.rb

@@ -28,10 +28,9 @@ module Google
       # Represents a Storage bucket. Belongs to a Project and has many Files.
       #
       # @example
-      #   require "google/cloud"
+      #   require "google/cloud/storage"
       #
-      #   gcloud = Google::Cloud.new
-      #   storage = gcloud.storage
+      #   storage = Google::Cloud::Storage.new
       #
       #   bucket = storage.bucket "my-bucket"
       #   file = bucket.file "path/to/my-file.ext"
@@ -101,10 +100,9 @@ module Google
         # @yieldparam [Bucket::Cors] cors the object accepting CORS rules
         #
         # @example Retrieving the bucket's CORS rules.
-        #   require "google/cloud"
+        #   require "google/cloud/storage"
         #
-        #   gcloud = Google::Cloud.new
-        #   storage = gcloud.storage
+        #   storage = Google::Cloud::Storage.new
         #
         #   bucket = storage.bucket "my-todo-app"
         #   bucket.cors #=> [{"origin"=>["http://example.org"],
@@ -113,10 +111,9 @@ module Google
         #               #     "maxAgeSeconds"=>3600}]
         #
         # @example Updating the bucket's CORS rules inside a block.
-        #   require "google/cloud"
+        #   require "google/cloud/storage"
         #
-        #   gcloud = Google::Cloud.new
-        #   storage = gcloud.storage
+        #   storage = Google::Cloud::Storage.new
         #   bucket = storage.bucket "my-todo-app"
         #
         #   bucket.update do |b|
@@ -201,7 +198,8 @@ module Google
         ##
         # 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`.
+        # `MULTI_REGIONAL`, `REGIONAL`, `NEARLINE`, `COLDLINE`, `STANDARD`,
+        # and `DURABLE_REDUCED_AVAILABILITY`.
         def storage_class
           @gapi.storage_class
         end
@@ -287,10 +285,9 @@ module Google
         #   file
         #
         # @example
-        #   require "google/cloud"
+        #   require "google/cloud/storage"
         #
-        #   gcloud = Google::Cloud.new
-        #   storage = gcloud.storage
+        #   storage = Google::Cloud::Storage.new
         #
         #   bucket = storage.bucket "my-bucket"
         #   bucket.update do |b|
@@ -301,10 +298,9 @@ module Google
         #   end
         #
         # @example New CORS rules can also be added in a nested block:
-        #   require "google/cloud"
+        #   require "google/cloud/storage"
         #
-        #   gcloud = Google::Cloud.new
-        #   storage = gcloud.storage
+        #   storage = Google::Cloud::Storage.new
         #   bucket = storage.bucket "my-todo-app"
         #
         #   bucket.update do |b|
@@ -334,10 +330,9 @@ module Google
         # @return [Boolean] Returns `true` if the bucket was deleted.
         #
         # @example
-        #   require "google/cloud"
+        #   require "google/cloud/storage"
         #
-        #   gcloud = Google::Cloud.new
-        #   storage = gcloud.storage
+        #   storage = Google::Cloud::Storage.new
         #
         #   bucket = storage.bucket "my-bucket"
         #   bucket.delete
@@ -374,10 +369,9 @@ module Google
         #   {Google::Cloud::Storage::File::List})
         #
         # @example
-        #   require "google/cloud"
+        #   require "google/cloud/storage"
         #
-        #   gcloud = Google::Cloud.new
-        #   storage = gcloud.storage
+        #   storage = Google::Cloud::Storage.new
         #
         #   bucket = storage.bucket "my-bucket"
         #   files = bucket.files
@@ -386,10 +380,9 @@ module Google
         #   end
         #
         # @example Retrieve all files: (See {File::List#all})
-        #   require "google/cloud"
+        #   require "google/cloud/storage"
         #
-        #   gcloud = Google::Cloud.new
-        #   storage = gcloud.storage
+        #   storage = Google::Cloud::Storage.new
         #
         #   bucket = storage.bucket "my-bucket"
         #   files = bucket.files
@@ -438,10 +431,9 @@ module Google
         #   not exist
         #
         # @example
-        #   require "google/cloud"
+        #   require "google/cloud/storage"
         #
-        #   gcloud = Google::Cloud.new
-        #   storage = gcloud.storage
+        #   storage = Google::Cloud::Storage.new
         #
         #   bucket = storage.bucket "my-bucket"
         #
@@ -539,20 +531,18 @@ module Google
         # @return [Google::Cloud::Storage::File]
         #
         # @example
-        #   require "google/cloud"
+        #   require "google/cloud/storage"
         #
-        #   gcloud = Google::Cloud.new
-        #   storage = gcloud.storage
+        #   storage = Google::Cloud::Storage.new
         #
         #   bucket = storage.bucket "my-bucket"
         #
         #   bucket.create_file "path/to/local.file.ext"
         #
         # @example Specifying a destination path:
-        #   require "google/cloud"
+        #   require "google/cloud/storage"
         #
-        #   gcloud = Google::Cloud.new
-        #   storage = gcloud.storage
+        #   storage = Google::Cloud::Storage.new
         #
         #   bucket = storage.bucket "my-bucket"
         #
@@ -560,11 +550,10 @@ module Google
         #                      "destination/path/file.ext"
         #
         # @example Providing a customer-supplied encryption key:
-        #   require "google/cloud"
+        #   require "google/cloud/storage"
         #   require "digest/sha2"
         #
-        #   gcloud = Google::Cloud.new
-        #   storage = gcloud.storage
+        #   storage = Google::Cloud::Storage.new
         #   bucket = storage.bucket "my-bucket"
         #
         #   # Key generation shown for example purposes only. Write your own.
@@ -604,6 +593,88 @@ module Google
         alias_method :upload_file, :create_file
         alias_method :new_file, :create_file
 
+        ##
+        # 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 identified by `path`. A URL can be
+        # created for paths that do not yet exist. For instance, a URL can be
+        # created to `PUT` file contents to.
+        #
+        # Generating a URL requires service account credentials, either by
+        # connecting with a service account when calling
+        # {Google::Cloud.storage}, or by passing in the service account `issuer`
+        # and `signing_key` values. Although the private key can be passed as a
+        # string for convenience, creating and storing an instance of
+        # `OpenSSL::PKey::RSA` is more efficient when making multiple calls to
+        # `signed_url`.
+        #
+        # A {SignedUrlUnavailable} is raised if the service account credentials
+        # are missing. Service account credentials are acquired by following the
+        # steps in [Service Account Authentication](
+        # https://cloud.google.com/storage/docs/authentication#service_accounts).
+        #
+        # @see https://cloud.google.com/storage/docs/access-control#Signed-URLs
+        #   Access Control Signed URLs guide
+        #
+        # @param [String] path Path to of the file in Google Cloud Storage.
+        # @param [String] method The HTTP verb to be used with the signed URL.
+        #   Signed URLs can be used
+        #   with `GET`, `HEAD`, `PUT`, and `DELETE` requests. Default is `GET`.
+        # @param [Integer] expires The number of seconds until the URL expires.
+        #   Default is 300/5 minutes.
+        # @param [String] content_type When provided, the client (browser) must
+        #   send this value in the HTTP header. e.g. `text/plain`
+        # @param [String] content_md5 The MD5 digest value in base64. If you
+        #   provide this in the string, the client (usually a browser) must
+        #   provide this HTTP header with this same value in its request.
+        # @param [String] issuer Service Account's Client Email.
+        # @param [String] client_email Service Account's Client Email.
+        # @param [OpenSSL::PKey::RSA, String] signing_key Service Account's
+        #   Private Key.
+        # @param [OpenSSL::PKey::RSA, String] private_key Service Account's
+        #   Private Key.
+        #
+        # @example
+        #   require "google/cloud/storage"
+        #
+        #   storage = Google::Cloud::Storage.new
+        #
+        #   bucket = storage.bucket "my-todo-app"
+        #   shared_url = bucket.signed_url "avatars/heidi/400x400.png",
+        #
+        # @example Any of the option parameters may be specified:
+        #   require "google/cloud/storage"
+        #
+        #   storage = Google::Cloud::Storage.new
+        #
+        #   bucket = storage.bucket "my-todo-app"
+        #   shared_url = bucket.signed_url "avatars/heidi/400x400.png",
+        #                                  method: "PUT",
+        #                                  expires: 300 # 5 minutes from now
+        #
+        # @example Using the `issuer` and `signing_key` options:
+        #   require "google/cloud/storage"
+        #
+        #   storage = Google::Cloud.storage
+        #
+        #   bucket = storage.bucket "my-todo-app"
+        #   key = OpenSSL::PKey::RSA.new "-----BEGIN PRIVATE KEY-----\n..."
+        #   shared_url = bucket.signed_url "avatars/heidi/400x400.png",
+        #                                  issuer: "service-account@gcloud.com",
+        #                                  signing_key: key
+        #
+        def signed_url path, method: nil, expires: nil, content_type: nil,
+                       content_md5: nil, issuer: nil, client_email: nil,
+                       signing_key: nil, private_key: nil
+          ensure_service!
+          options = { method: method, expires: expires,
+                      content_type: content_type, content_md5: content_md5,
+                      issuer: issuer, client_email: client_email,
+                      signing_key: signing_key, private_key: private_key }
+          signer = File::Signer.from_bucket self, path
+          signer.signed_url options
+        end
+
         ##
         # The Bucket::Acl instance used to control access to the bucket.
         #
@@ -615,10 +686,9 @@ module Google
         #   Control guide
         #
         # @example Grant access to a user by prepending `"user-"` to an email:
-        #   require "google/cloud"
+        #   require "google/cloud/storage"
         #
-        #   gcloud = Google::Cloud.new
-        #   storage = gcloud.storage
+        #   storage = Google::Cloud::Storage.new
         #
         #   bucket = storage.bucket "my-todo-app"
         #
@@ -626,10 +696,9 @@ module Google
         #   bucket.acl.add_reader "user-#{email}"
         #
         # @example Grant access to a group by prepending `"group-"` to an email:
-        #   require "google/cloud"
+        #   require "google/cloud/storage"
         #
-        #   gcloud = Google::Cloud.new
-        #   storage = gcloud.storage
+        #   storage = Google::Cloud::Storage.new
         #
         #   bucket = storage.bucket "my-todo-app"
         #
@@ -637,10 +706,9 @@ module Google
         #   bucket.acl.add_reader "group-#{email}"
         #
         # @example Or, grant access via a predefined permissions list:
-        #   require "google/cloud"
+        #   require "google/cloud/storage"
         #
-        #   gcloud = Google::Cloud.new
-        #   storage = gcloud.storage
+        #   storage = Google::Cloud::Storage.new
         #
         #   bucket = storage.bucket "my-todo-app"
         #
@@ -662,10 +730,9 @@ module Google
         #   Control guide
         #
         # @example Grant access to a user by prepending `"user-"` to an email:
-        #   require "google/cloud"
+        #   require "google/cloud/storage"
         #
-        #   gcloud = Google::Cloud.new
-        #   storage = gcloud.storage
+        #   storage = Google::Cloud::Storage.new
         #
         #   bucket = storage.bucket "my-todo-app"
         #
@@ -673,10 +740,9 @@ module Google
         #   bucket.default_acl.add_reader "user-#{email}"
         #
         # @example Grant access to a group by prepending `"group-"` to an email
-        #   require "google/cloud"
+        #   require "google/cloud/storage"
         #
-        #   gcloud = Google::Cloud.new
-        #   storage = gcloud.storage
+        #   storage = Google::Cloud::Storage.new
         #
         #   bucket = storage.bucket "my-todo-app"
         #
@@ -684,10 +750,9 @@ module Google
         #   bucket.default_acl.add_reader "group-#{email}"
         #
         # @example Or, grant access via a predefined permissions list:
-        #   require "google/cloud"
+        #   require "google/cloud/storage"
         #
-        #   gcloud = Google::Cloud.new
-        #   storage = gcloud.storage
+        #   storage = Google::Cloud::Storage.new
         #
         #   bucket = storage.bucket "my-todo-app"
         #