From b92062d56dbb56b449abae22af42902556592832 Mon Sep 17 00:00:00 2001
From: Vipul A M <vipul@saeloun.com>
Date: Sun, 31 Mar 2024 14:33:01 -0400
Subject: [PATCH] Start explaining storing behaviour at various places for file
 upload. Closes #155 (#157)

* Fix wrong param name used in docs for method definition

* Mention in docs at various placea about auto store file behavior

* Cleanup this documentation

* Make sure the values for store are properly annotated as objects

* Missing option

* Updates to section about passing params per request. Also remove the irrelevant autostore option. We don't really support configuring it
---
 README.md                                     | 27 ++++++++++---------
 .../entity/conversion/base_converter.rb       |  2 +-
 2 files changed, 16 insertions(+), 13 deletions(-)

diff --git a/README.md b/README.md
index c277815..7c98637 100644
--- a/README.md
+++ b/README.md
@@ -95,7 +95,7 @@ Using Uploadcare is simple, and here are the basics of handling files.
 ```ruby
 @file_to_upload = File.open("your-file.png")
 
-@uc_file = Uploadcare::Uploader.upload(@file_to_upload)
+@uc_file = Uploadcare::Uploader.upload(@file_to_upload, store: "auto")
 
 @uc_file.uuid
 # => "dc99200d-9bd6-4b43-bfa9-aa7bfaefca40"
@@ -105,13 +105,15 @@ Using Uploadcare is simple, and here are the basics of handling files.
 # => "https://ucarecdn.com/dc99200d-9bd6-4b43-bfa9-aa7bfaefca40/your-file.png"
 ```
 
-Your might then want to store or delete the uploaded file. Storing files could
-be crucial if you aren't using the “Automatic file storing” option for your
-Uploadcare project. If not stored manually or automatically, files get deleted
-within a 24-hour period.
+The `store` option can have these possible values:
+- `true`: mark the uploaded file as stored.
+- `false`: do not mark the uploaded file as stored and remove it after 24 hours.
+- `"auto"`: defers the choice of storage behavior to the [auto-store setting](https://app.uploadcare.com/projects/-/settings/#storage) for your Uploadcare project. This is the default behavior.
+
+Your might then want to store or delete the uploaded file.
 
 ```ruby
-# that's how you store a file
+# that's how you store a file, if you have uploaded the file using store: false and changed your mind later
 @uc_file.store
 # => #<Uploadcare::Api::File ...
 
@@ -128,16 +130,16 @@ Uploadcare supports multiple ways to upload files:
 # Smart upload - detects type of passed object and picks appropriate upload method
 # If you have a large file (more than 100Mb / 10485760 bytes), the uploader will automatically process it with a multipart upload
 
-Uploadcare::Uploader.upload("https://placekitten.com/96/139")
+Uploadcare::Uploader.upload("https://placekitten.com/96/139", store: "auto")
 ```
 
 There are explicit ways to select upload type:
 
 ```ruby
 files = [File.open("1.jpg"), File.open("1.jpg")]
-Uploadcare::Uploader.upload_files(files)
+Uploadcare::Uploader.upload_files(files, store: 'auto')
 
-Uploadcare::Uploader.upload_from_url("https://placekitten.com/96/139")
+Uploadcare::Uploader.upload_from_url("https://placekitten.com/96/139", store: "auto")
 ```
 It is possible to track progress of the upload-from-URL process. To do that, you should specify the `async` option and get a token:
 
@@ -188,11 +190,12 @@ Options available in a block:
 
 #### Uploading options
 
-You can override global [`:autostore`](#initialization) option for each upload request:
+You can override [auto-store setting](https://app.uploadcare.com/projects/-/settings/#storage) from your Uploadcare project for each upload request:
 
 ```ruby
-@api.upload(files, store: true)
-@api.upload_from_url(url, store: :auto)
+@api.upload(files, store: true)          # mark the uploaded file as stored.
+@api.upload(files, store: false)         # do not mark the uploaded file as stored and remove it after 24 hours.
+@api.upload_from_url(url, store: "auto") # defers the choice of storage behavior to the auto-store setting.
 ```
 
 You can upload file with custom metadata, for example `subsystem` and `pet`:
diff --git a/lib/uploadcare/entity/conversion/base_converter.rb b/lib/uploadcare/entity/conversion/base_converter.rb
index 89df484..786c70a 100644
--- a/lib/uploadcare/entity/conversion/base_converter.rb
+++ b/lib/uploadcare/entity/conversion/base_converter.rb
@@ -9,7 +9,7 @@ class BaseConverter < Entity
         class << self
           # Converts files
           #
-          # @param doc_params [Array] of hashes with params or [Hash]
+          # @param params [Array] of hashes with params or [Hash]
           # @option options [Boolean] :store whether to store file on servers.
           def convert(params, options = {})
             files_params = params.is_a?(Hash) ? [params] : params