Clarify File/IO documentation

blowmage · blowmage · commit ea4e6252486d · 2018-04-13T16:27:55.000-06:00
Update documentation to clarify the need for a File-like IO object
to create GCS File/Objects with.
The underlying libraries call #size on the object, which is not
present on IO, but is present on File and StringIO.
diff --git a/google-cloud-storage/lib/google/cloud/storage/bucket.rb b/google-cloud-storage/lib/google/cloud/storage/bucket.rb
@@ -561,8 +561,8 @@ def file path, generation: nil, skip_lookup: nil, encryption_key: nil
 
         ##
         # Creates a new {File} object by providing a path to a local file (or
-        # any IO or IO-ish object) to upload, along with the path at which to
-        # store it in the bucket.
+        # any File-like object such as StringIO) to upload, along with the path
+        # at which to store it in the bucket.
         #
         # #### Customer-supplied encryption keys
         #
@@ -577,9 +577,9 @@ def file path, generation: nil, skip_lookup: nil, encryption_key: nil
         # and you can read or update the metadata of an encrypted file without
         # providing the encryption key.
         #
-        # @param [String, IO] file Path of the file on the filesystem to
-        #   upload. Can be an IO object, or IO-ish object like StringIO. (If the
-        #   IO object does not have path, a `path` argument must be also be
+        # @param [String, ::File] file Path of the file on the filesystem to
+        #   upload. Can be an File object, or File-like object such as StringIO.
+        #   (If the object does not have path, a `path` argument must be also be
         #   provided.)
         # @param [String] path Path to store the file in Google Cloud Storage.
         # @param [String] acl A predefined set of access controls to apply to
diff --git a/google-cloud-storage/lib/google/cloud/storage/file.rb b/google-cloud-storage/lib/google/cloud/storage/file.rb
@@ -411,7 +411,7 @@ def update
         end
 
         ##
-        # Download the file's contents to a local file or an IO instance.
+        # Download the file's contents to a local file or an File-like object.
         #
         # By default, the download is verified by calculating the MD5 digest.
         #
@@ -420,11 +420,12 @@ def update
         # was used with {Bucket#create_file}, the `encryption_key` option must
         # be provided.
         #
-        # @param [String, IO] path The path on the local file system to write
-        #   the data to. The path provided must be writable. Can also be an IO
-        #   object, or IO-ish object like StringIO. If an IO object, the object
-        #   will be written to, not the filesystem. If omitted, a new StringIO
-        #   instance will be written to and returned. Optional.
+        # @param [String, ::File] path The path on the local file system to
+        #   write the data to. The path provided must be writable. Can also be
+        #   an File object, or File-like object such as StringIO. If an file
+        #   object, the object will be written to, not the filesystem. If
+        #   omitted, a new StringIO instance will be written to and returned.
+        #   Optional.
         # @param [Symbol] verify The verification algorithm used to ensure the
         #   downloaded file contents are correct. Default is `:md5`.
         #
@@ -446,11 +447,11 @@ def update
         #   not performed in the Storage service. (See [Transcoding of
         #   gzip-compressed files](https://cloud.google.com/storage/docs/transcoding))
         #
-        # @return [IO] Returns an IO object representing the file data. This
-        #   will ordinarily be a `::File` object referencing the local file
-        #   system. However, if the argument to `path` is `nil`, a StringIO
-        #   instance will be returned. If the argument to `path` is an IO
-        #   object, then that object will be returned.
+        # @return [::File, StringIO] Returns a file object representing the file
+        #   data. This will ordinarily be a `::File` object referencing the
+        #   local file system. However, if the argument to `path` is `nil`, a
+        #   StringIO instance will be returned. If the argument to `path` is an
+        #   File-like object, then that object will be returned.
         #
         # @example
         #   require "google/cloud/storage"
