From 6a282eccdd7dcea3431c94c0f9c153e9fce75b0d Mon Sep 17 00:00:00 2001 From: BurdetteLamar Date: Thu, 29 Dec 2022 18:16:27 +0000 Subject: [PATCH] Enhanced RDoc for HTTPHeader --- lib/net/http/header.rb | 39 +++++++++++++++++++++++++++++---------- 1 file changed, 29 insertions(+), 10 deletions(-) diff --git a/lib/net/http/header.rb b/lib/net/http/header.rb index bc4660ea..f7aa1033 100644 --- a/lib/net/http/header.rb +++ b/lib/net/http/header.rb @@ -763,19 +763,38 @@ def set_content_type(type, params = {}) alias content_type= set_content_type - # Set header fields and a body from HTML form data. - # +params+ should be an Array of Arrays or - # a Hash containing HTML form data. - # Optional argument +sep+ means data record separator. + # Sets the request body to a URL-encoded string derived from argument +params+, + # and sets request header field 'Content-Type' + # to 'application/x-www-form-urlencoded'. # - # Values are URL encoded as necessary and the content-type is set to - # application/x-www-form-urlencoded + # The resulting request is suitable for HTTP request +POST+ or +PUT+. # - # Example: + # Argument +params+ must be suitable for use as argument +enum+ to + # {URI.encode_www_form}[https://docs.ruby-lang.org/en/master/URI.html#method-c-encode_www_form]. + # + # With only argument +params+ given, + # sets the body to a URL-encoded string with the default separator '&': + # + # req = Net::HTTP::Post.new('example.com') + # + # req.set_form_data(q: 'ruby', lang: 'en') + # req.body # => "q=ruby&lang=en" + # req['Content-Type'] # => "application/x-www-form-urlencoded" + # + # req.set_form_data([['q', 'ruby'], ['lang', 'en']]) + # req.body # => "q=ruby&lang=en" + # + # req.set_form_data(q: ['ruby', 'perl'], lang: 'en') + # req.body # => "q=ruby&q=perl&lang=en" + # + # req.set_form_data([['q', 'ruby'], ['q', 'perl'], ['lang', 'en']]) + # req.body # => "q=ruby&q=perl&lang=en" + # + # With string argument +sep+ also given, + # uses that string as the separator: # - # http.form_data = {"q" => "ruby", "lang" => "en"} - # http.form_data = {"q" => ["ruby", "perl"], "lang" => "en"} - # http.set_form_data({"q" => "ruby", "lang" => "en"}, ';') + # req.set_form_data({q: 'ruby', lang: 'en'}, '|') + # req.body # => "q=ruby|lang=en" # # Net::HTTPHeader#form_data= is an alias for Net::HTTPHeader#set_form_data. def set_form_data(params, sep = '&')