[ruby/net-http] [DOC] Enhanced RDoc for set_form

(https://github.com/ruby/net-http/pull/103)

https://github.com/ruby/net-http/commit/f6506ff889

lib/net/http/header.rb

@@ -806,56 +806,108 @@ module Net::HTTPHeader
 
   alias form_data= set_form_data
 
-  # Set an HTML form data set.
+  # Stores form data to be used in a +POST+ or +PUT+ request.
-  # +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.
   #
-  # Each item of params should respond to +each+ and yield 2-3 arguments,
+  # The form data given in +params+ consists of zero or more fields;
-  # or an array of 2-3 elements. The arguments yielded should be:
+  # each field is:
   #
-  # - The name of the field.
+  # - A scalar value.
-  # - The value of the field, it should be a String or a File or IO-like.
+  # - A name/value pair.
-  # - An options hash, supporting the following options
+  # - An IO stream opened for reading.
-  #   (used only for file uploads); entries:
+  #
+  # Argument +params+ should be an
+  # {Enumerable}[rdoc-ref:Enumerable@Enumerable+in+Ruby+Classes]
+  # (method <tt>params.map</tt> will be called),
+  # and is often an array or hash.
+  #
+  # First, we set up a request:
+  #
+  #   _uri = uri.dup
+  #   _uri.path ='/posts'
+  #   req = Net::HTTP::Post.new(_uri)
+  #
+  # <b>Argument +params+ As an Array</b>
+  #
+  # When +params+ is an array,
+  # each of its elements is a subarray that defines a field;
+  # the subarray may contain:
+  #
+  # - One string:
+  #
+  #     req.set_form([['foo'], ['bar'], ['baz']])
+  #
+  # - Two strings:
+  #
+  #     req.set_form([%w[foo 0], %w[bar 1], %w[baz 2]])
+  #
+  # - When argument +enctype+ (see below) is given as
+  #   <tt>'multipart/form-data'</tt>:
+  #
+  #   - A string name and an IO stream opened for reading:
+  #
+  #       require 'stringio'
+  #       req.set_form([['file', StringIO.new('Ruby is cool.')]])
+  #
+  #   - A string name, an IO stream opened for reading,
+  #     and an options hash, which may contain these entries:
   #
   #     - +: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+ hash has a :filename key,
-  # the item is treated as a file field.
-  #
-  # If Transfer-Encoding is set as chunked, this sends the request using
-  # chunked encoding. Because chunked encoding is HTTP/1.1 feature,
-  # you should confirm that the server supports HTTP/1.1 before using
-  # chunked encoding.
-  #
   #     Example:
   #
-  #    req.set_form([["q", "ruby"], ["lang", "en"]])
+  #       req.set_form([['file', file, {filename: "other-filename.foo"}]]
   #
-  #    req.set_form({"f"=>File.open('/path/to/filename')},
+  # The various forms may be mixed:
-  #                 "multipart/form-data",
-  #                 charset: "UTF-8",
-  #    )
   #
-  #    req.set_form([["f",
+  #   req.set_form(['foo', %w[bar 1], ['file', file]])
-  #                   File.open('/path/to/filename.bar'),
-  #                   {filename: "other-filename.foo"}
-  #                 ]],
-  #                 "multipart/form-data",
-  #    )
   #
-  # See also RFC 2388, RFC 2616, HTML 4.01, and HTML5
+  # <b>Argument +params+ As a Hash</b>
+  #
+  # When +params+ is a hash,
+  # each of its entries is a name/value pair that defines a field:
+  #
+  # - The name is a string.
+  # - The value may be:
+  #
+  #   - +nil+.
+  #   - Another string.
+  #   - An IO stream opened for reading
+  #     (only when argument +enctype+ -- see below -- is given as
+  #     <tt>'multipart/form-data'</tt>).
+  #
+  # Examples:
+  #
+  #   # Nil-valued fields.
+  #   req.set_form({'foo' => nil, 'bar' => nil, 'baz' => nil})
+  #
+  #   # String-valued fields.
+  #   req.set_form({'foo' => 0, 'bar' => 1, 'baz' => 2})
+  #
+  #   # IO-valued field.
+  #   require 'stringio'
+  #   req.set_form({'file' => StringIO.new('Ruby is cool.')})
+  #
+  #   # Mixture of fields.
+  #   req.set_form({'foo' => nil, 'bar' => 1, 'file' => file})
+  #
+  # Optional argument +enctype+ specifies the value to be given
+  # to field <tt>'Content-Type'</tt>, and must be one of:
+  #
+  # - <tt>'application/x-www-form-urlencoded'</tt> (the default).
+  # - <tt>'multipart/form-data'</tt>;
+  #   see {RFC 7578}[https://www.rfc-editor.org/rfc/rfc7578].
+  #
+  # Optional argument +formopt+ is a hash of options
+  # (applicable only when argument +enctype+
+  # is <tt>'multipart/form-data'</tt>)
+  # that may include the following entries:
+  #
+  # - +:boundary+: The value is the boundary string for the multipart message.
+  #   If not given, the boundary is a random string.
+  #   See {Boundary}[https://www.rfc-editor.org/rfc/rfc7578#section-4.1].
+  # - +:charset+: Value is the character set for the form submission.
+  #   Field names and values of non-file fields should be encoded with this charset.
   #
   def set_form(params, enctype='application/x-www-form-urlencoded', formopt={})
     @body_data = params