summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorJeremy Evans <code@jeremyevans.net>2020-05-27 13:13:46 -0700
committerJeremy Evans <code@jeremyevans.net>2020-05-27 13:13:46 -0700
commitfa380208fe4ef36cd6a8535d3ac43e61c7935f1c (patch)
tree58f9a0726d3060b29a41b87ddd177169cf6491a4
parent9cfef5b494c2849ee232c53431dfbc21b345c4e4 (diff)
Improve documentation for Net::HTTPHeader#set_form [ci skip]
Fixes [Misc #16916]
-rw-r--r--lib/net/http/header.rb52
1 files changed, 36 insertions, 16 deletions
diff --git a/lib/net/http/header.rb b/lib/net/http/header.rb
index 8641be4eae..a8901e79cb 100644
--- a/lib/net/http/header.rb
+++ b/lib/net/http/header.rb
@@ -423,30 +423,50 @@ module Net::HTTPHeader
alias form_data= set_form_data
# Set an HTML form data set.
- # +params+ is the form data set; it is an Array of Arrays or a Hash
- # +enctype is the type to encode the form data set.
- # It is application/x-www-form-urlencoded or multipart/form-data.
- # +formopt+ is an optional hash to specify the detail.
+ # +params+ :: The form data to set, which should be an enumerable.
+ # See below for more details.
+ # +enctype+ :: The content type to use to encode the form submission,
+ # which should be application/x-www-form-urlencoded or
+ # multipart/form-data.
+ # +formopt+ :: An options hash, supporting the following options:
+ # :boundary :: The boundary of the multipart message. If
+ # not given, a random boundary will be used.
+ # :charset :: The charset of the form submission. All
+ # field names and values of non-file fields
+ # should be encoded with this charset.
#
- # boundary:: the boundary of the multipart message
- # charset:: the charset of the message. All names and the values of
- # non-file fields are encoded as the charset.
- #
- # Each item of params is an array and contains following items:
- # +name+:: the name of the field
- # +value+:: the value of the field, it should be a String or a File
- # +opt+:: an optional hash to specify additional information
+ # Each item of params should respond to +each+ and yield 2-3 arguments,
+ # or an array of 2-3 elements. The arguments yielded should be:
+ # * The name of the field.
+ # * The value of the field, it should be a String or a File or IO-like.
+ # * An options hash, supporting the following options, only
+ # used for file uploads:
+ # :filename :: The name of the file to use.
+ # :content_type :: The content type of the uploaded file.
#
# Each item is a file field or a normal field.
- # If +value+ is a File object or the +opt+ have a filename key,
+ # If +value+ is a File object or the +opt+ hash has a :filename key,
# the item is treated as a file field.
#
- # If Transfer-Encoding is set as chunked, this send the request in
+ # If Transfer-Encoding is set as chunked, this sends the request using
# chunked encoding. Because chunked encoding is HTTP/1.1 feature,
- # you must confirm the server to support HTTP/1.1 before sending it.
+ # you should confirm that the server supports HTTP/1.1 before using
+ # chunked encoding.
#
# Example:
- # http.set_form([["q", "ruby"], ["lang", "en"]])
+ # req.set_form([["q", "ruby"], ["lang", "en"]])
+ #
+ # req.set_form({"f"=>File.open('/path/to/filename')},
+ # "multipart/form-data",
+ # charset: "UTF-8",
+ # )
+ #
+ # req.set_form([["f",
+ # File.open('/path/to/filename.bar'),
+ # {filename: "other-filename.foo"}
+ # ]],
+ # "multipart/form-data",
+ # )
#
# See also RFC 2388, RFC 2616, HTML 4.01, and HTML5
#