file.rb in google-cloud-storage-1.13.1

- old
+ new

@@ -106,193 +106,275 @@
         end
 
         ##
         # The kind of item this is.
         # For files, this is always storage#object.
+        #
+        # @return [String]
+        #
         def kind
           @gapi.kind
         end
 
         ##
         # The ID of the file.
+        #
+        # @return [String]
+        #
         def id
           @gapi.id
         end
 
         ##
         # The name of this file.
+        #
+        # @return [String]
+        #
         def name
           @gapi.name
         end
 
         ##
         # The name of the {Bucket} containing this file.
+        #
+        # @return [String]
+        #
         def bucket
           @gapi.bucket
         end
 
         ##
         # The content generation of this file.
         # Used for object versioning.
+        #
+        # @return [Fixnum]
+        #
         def generation
           @gapi.generation
         end
 
         ##
         # The version of the metadata for this file at this generation.
         # Used for preconditions and for detecting changes in metadata.
         # A metageneration number is only meaningful in the context of a
         # particular generation of a particular file.
+        #
+        # @return [Fixnum]
+        #
         def metageneration
           @gapi.metageneration
         end
 
         ##
         # A URL that can be used to access the file using the REST API.
+        #
+        # @return [String]
+        #
         def api_url
           @gapi.self_link
         end
 
         ##
         # A URL that can be used to download the file using the REST API.
+        #
+        # @return [String]
+        #
         def media_url
           @gapi.media_link
         end
 
         ##
         # Content-Length of the data in bytes.
+        #
+        # @return [Integer]
+        #
         def size
           @gapi.size.to_i if @gapi.size
         end
 
         ##
         # Creation time of the file.
+        #
+        # @return [DateTime]
+        #
         def created_at
           @gapi.time_created
         end
 
         ##
         # The creation or modification time of the file.
         # For buckets with versioning enabled, changing an object's
         # metadata does not change this property.
+        #
+        # @return [DateTime]
+        #
         def updated_at
           @gapi.updated
         end
 
         ##
         # MD5 hash of the data; encoded using base64.
+        #
+        # @return [String]
+        #
         def md5
           @gapi.md5_hash
         end
 
         ##
         # The CRC32c checksum of the data, as described in
         # [RFC 4960, Appendix B](http://tools.ietf.org/html/rfc4960#appendix-B).
         # Encoded using base64 in big-endian byte order.
+        #
+        # @return [String]
+        #
         def crc32c
           @gapi.crc32c
         end
 
         ##
         # HTTP 1.1 Entity tag for the file.
+        #
+        # @return [String]
+        #
         def etag
           @gapi.etag
         end
 
         ##
         # The [Cache-Control](https://tools.ietf.org/html/rfc7234#section-5.2)
-        # directive for the file data.
+        # directive for the file data. If omitted, and the file is accessible
+        # to all anonymous users, the default will be `public, max-age=3600`.
+        #
+        # @return [String]
+        #
         def cache_control
           @gapi.cache_control
         end
 
         ##
         # Updates the
         # [Cache-Control](https://tools.ietf.org/html/rfc7234#section-5.2)
-        # directive for the file data.
+        # directive for the file data. If omitted, and the file is accessible
+        # to all anonymous users, the default will be `public, max-age=3600`.
+        #
+        # @param [String] cache_control The Cache-Control directive.
+        #
         def cache_control= cache_control
           @gapi.cache_control = cache_control
           update_gapi! :cache_control
         end
 
         ##
         # The [Content-Disposition](https://tools.ietf.org/html/rfc6266) of the
         # file data.
+        #
+        # @return [String]
+        #
         def content_disposition
           @gapi.content_disposition
         end
 
         ##
         # Updates the [Content-Disposition](https://tools.ietf.org/html/rfc6266)
         # of the file data.
+        #
+        # @param [String] content_disposition The Content-Disposition of the
+        #   file.
+        #
         def content_disposition= content_disposition
           @gapi.content_disposition = content_disposition
           update_gapi! :content_disposition
         end
 
         ##
         # The [Content-Encoding
         # ](https://tools.ietf.org/html/rfc7231#section-3.1.2.2) of the file
         # data.
+        #
+        # @return [String]
+        #
         def content_encoding
           @gapi.content_encoding
         end
 
         ##
         # Updates the [Content-Encoding
         # ](https://tools.ietf.org/html/rfc7231#section-3.1.2.2) of the file
         # data.
+        #
+        # @param [String] content_encoding The Content-Encoding of the file.
+        #
         def content_encoding= content_encoding
           @gapi.content_encoding = content_encoding
           update_gapi! :content_encoding
         end
 
         ##
         # The [Content-Language](http://tools.ietf.org/html/bcp47) of the file
         # data.
+        #
+        # @return [String]
+        #
         def content_language
           @gapi.content_language
         end
 
         ##
         # Updates the [Content-Language](http://tools.ietf.org/html/bcp47) of
         # the file data.
+        #
+        # @param [String] content_language The Content-Language of the file.
+        #
         def content_language= content_language
           @gapi.content_language = content_language
           update_gapi! :content_language
         end
 
         ##
         # The [Content-Type](https://tools.ietf.org/html/rfc2616#section-14.17)
         # of the file data.
+        #
+        # @return [String]
+        #
         def content_type
           @gapi.content_type
         end
 
         ##
         # Updates the
         # [Content-Type](https://tools.ietf.org/html/rfc2616#section-14.17) of
         # the file data.
+        #
+        # @param [String] content_type The Content-Type of the file.
+        #
         def content_type= content_type
           @gapi.content_type = content_type
           update_gapi! :content_type
         end
 
         ##
         # A hash of custom, user-provided web-safe keys and arbitrary string
         # values that will returned with requests for the file as "x-goog-meta-"
         # response headers.
+        #
+        # @return [Hash(String => String)]
+        #
         def metadata
           m = @gapi.metadata
           m = m.to_h if m.respond_to? :to_h
           m.dup.freeze
         end
 
         ##
         # Updates the hash of custom, user-provided web-safe keys and arbitrary
         # string values that will returned with requests for the file as
         # "x-goog-meta-" response headers.
+        #
+        # @param [Hash(String => String)] metadata The user-provided metadata,
+        #   in key/value pairs.
+        #
         def metadata= metadata
           @gapi.metadata = metadata
           update_gapi! :metadata
         end
 
@@ -301,10 +383,13 @@
         # Base64-encoded string of the SHA256 hash of the [customer-supplied
         # encryption
         # key](https://cloud.google.com/storage/docs/encryption#customer-supplied).
         # You can use this SHA256 hash to uniquely identify the AES-256
         # encryption key required to decrypt this file.
+        #
+        # @return [String]
+        #
         def encryption_key_sha256
           return nil unless @gapi.customer_encryption
           Base64.decode64 @gapi.customer_encryption.key_sha256
         end
 
@@ -316,13 +401,10 @@
         #   Documentation
         #
         # @return [String, nil] A Cloud KMS encryption key, or `nil` if none has
         #   been configured.
         #
-        # @see https://cloud.google.com/kms/docs/ Cloud Key Management Service
-        #   Documentation
-        #
         def kms_key
           @gapi.kms_key_name
         end
 
         ##
@@ -330,10 +412,13 @@
         # determines the SLA and the cost of storage. For more information, see
         # [Storage
         # Classes](https://cloud.google.com/storage/docs/storage-classes) and
         # [Per-Object Storage
         # Class](https://cloud.google.com/storage/docs/per-object-storage-class).
+        #
+        # @return [String]
+        #
         def storage_class
           @gapi.storage_class
         end
 
         ##
@@ -350,11 +435,13 @@
         # Classes](https://cloud.google.com/storage/docs/storage-classes) and
         # [Per-Object Storage
         # Class](https://cloud.google.com/storage/docs/per-object-storage-class).
         # The  default value is the default storage class for the bucket. See
         # {Bucket#storage_class}.
+        #
         # @param [Symbol, String] storage_class Storage class of the file.
+        #
         def storage_class= storage_class
           @gapi.storage_class = storage_class_for(storage_class)
           update_gapi! :storage_class
         end
 
@@ -364,11 +451,11 @@
         # Useful for listing archived versions of the file, restoring the live
         # version of the file to an older version, or deleting an archived
         # version. You can turn versioning on or off for a bucket at any time
         # with {Bucket#versioning=}. Turning versioning off leaves existing file
         # versions in place and causes the bucket to stop accumulating new
-        # archived object versions. (See {Bucket#versioning} and
+        # archived object versions. (See {Bucket#versioning?} and
         # {File#generation})
         #
         # @see https://cloud.google.com/storage/docs/object-versioning Object
         #   Versioning
         #
@@ -950,16 +1037,16 @@
         end
 
         ##
         # Permanently deletes the file.
         #
-        # @return [Boolean] Returns `true` if the file was deleted.
         # @param [Boolean, Integer] generation Specify a version of the file to
         #   delete. When `true`, it will delete the version returned by
         #   {#generation}. The default behavior is to delete the latest version
         #   of the file (regardless of the version to which the file is set,
         #   which is the version returned by {#generation}.)
+        # @return [Boolean] Returns `true` if the file was deleted.
         #
         # @example
         #   require "google/cloud/storage"
         #
         #   storage = Google::Cloud::Storage.new
@@ -1007,10 +1094,12 @@
         #   Accessing Public Data
         #
         # @param [String] protocol The protocol to use for the URL. Default is
         #   `HTTPS`.
         #
+        # @return [String]
+        #
         # @example
         #   require "google/cloud/storage"
         #
         #   storage = Google::Cloud::Storage.new
         #
@@ -1079,10 +1168,12 @@
         #   `response-content-type` can alter the behavior of the response when
         #   using the URL, but only when the file resource is missing the
         #   corresponding values. (These values can be permanently set using
         #   {#content_disposition=} and {#content_type=}.)
         #
+        # @return [String]
+        #
         # @example
         #   require "google/cloud/storage"
         #
         #   storage = Google::Cloud::Storage.new
         #
@@ -1147,10 +1238,12 @@
         # as many predefined lists.
         #
         # @see https://cloud.google.com/storage/docs/access-control Access
         #   Control guide
         #
+        # @return [File::Acl]
+        #
         # @example Grant access to a user by prepending `"user-"` to an email:
         #   require "google/cloud/storage"
         #
         #   storage = Google::Cloud::Storage.new
         #
@@ -1421,17 +1514,24 @@
 
           ##
           # A hash of custom, user-provided web-safe keys and arbitrary string
           # values that will returned with requests for the file as
           # "x-goog-meta-" response headers.
+          #
+          # @return [Hash(String => String)]
+          #
           def metadata
             @metadata
           end
 
           ##
           # Updates the hash of custom, user-provided web-safe keys and
           # arbitrary string values that will returned with requests for the
           # file as "x-goog-meta-" response headers.
+          #
+          # @param [Hash(String => String)] metadata The user-provided metadata,
+          #   in key/value pairs.
+          #
           def metadata= metadata
             @metadata = metadata
             @gapi.metadata = @metadata
             update_gapi! :metadata
           end