https://git.ruby-lang.org/ruby.git/commit/?id=fa380208fe

From fa380208fe4ef36cd6a8535d3ac43e61c7935f1c Mon Sep 17 00:00:00 2001
From: Jeremy Evans <code@j...>
Date: Wed, 27 May 2020 13:13:46 -0700
Subject: Improve documentation for Net::HTTPHeader#set_form [ci skip]

Fixes [Misc #16916]

diff --git a/lib/net/http/header.rb b/lib/net/http/header.rb
index 8641be4..a8901e7 100644
--- a/lib/net/http/header.rb
+++ b/lib/net/http/header.rb
@@ -423,30 +423,50 @@ module Net::HTTPHeader https://github.com/ruby/ruby/blob/trunk/lib/net/http/header.rb#L423
   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
   #
-- 
cgit v0.10.2


--
ML: ruby-changes@q...
Info: http://www.atdot.net/~ko1/quickml/