From fd98169e00a050fab2e7f1a1cefcc92be4c8cb40 Mon Sep 17 00:00:00 2001
From: Burdette Lamar <BurdetteLamar@Yahoo.com>
Date: Sat, 7 Jan 2023 13:22:31 -0600
Subject: [ruby/uri] [DOC] Common rdoc (https://github.com/ruby/uri/pull/52)

https://github.com/ruby/uri/commit/be8047028f
---
 lib/uri/common.rb | 18 ++++++++++++------
 1 file changed, 12 insertions(+), 6 deletions(-)

(limited to 'lib')

diff --git a/lib/uri/common.rb b/lib/uri/common.rb
index ac72a9ebc2..afb124678a 100644
--- a/lib/uri/common.rb
+++ b/lib/uri/common.rb
@@ -330,6 +330,8 @@ module URI
   #   and then to encoding +enc+.
   #
   # In either case, the returned string has forced encoding Encoding::US_ASCII.
+  #
+  # Related: URI.encode_uri_component (encodes <tt>' '</tt> as <tt>'%20'</tt>).
   def self.encode_www_form_component(str, enc=nil)
     _encode_uri_component(/[^*\-.0-9A-Z_a-z]/, TBLENCWWWCOMP_, str, enc)
   end
@@ -362,20 +364,18 @@ module URI
   #     URI.decode_www_form_component('Here+are+some+punctuation+characters%3A+%2C%3B%3F%3A')
   #     # => "Here are some punctuation characters: ,;?:"
   #
+  # Related: URI.decode_uri_component (preserves <tt>'+'</tt>).
   def self.decode_www_form_component(str, enc=Encoding::UTF_8)
     _decode_uri_component(/\+|%\h\h/, str, enc)
   end
 
-  # Encodes +str+ using URL encoding
-  #
-  # This encodes SP to %20 instead of +.
+  # Like URI.encode_www_form_component, except that <tt>' '</tt> (space)
+  # is encoded as <tt>'%20'</tt> (instead of <tt>'+'</tt>).
   def self.encode_uri_component(str, enc=nil)
     _encode_uri_component(/[^*\-.0-9A-Z_a-z]/, TBLENCURICOMP_, str, enc)
   end
 
-  # Decodes given +str+ of URL-encoded data.
-  #
-  # This does not decode + to SP.
+  # Like URI.decode_www_form_component, except that <tt>'+'</tt> is preserved.
   def self.decode_uri_component(str, enc=Encoding::UTF_8)
     _decode_uri_component(/%\h\h/, str, enc)
   end
@@ -419,6 +419,12 @@ module URI
   #   URI.encode_www_form({foo: 0, bar: 1, baz: 2})
   #   # => "foo=0&bar=1&baz=2"
   #
+  # The returned string is formed using method URI.encode_www_form_component,
+  # which converts certain characters:
+  #
+  #   URI.encode_www_form('f#o': '/', 'b-r': '$')
+  #   # => "f%23o=%2F&b-r=%24"
+  #
   # When +enum+ is Array-like, each element +ele+ is converted to a field:
   #
   # - If +ele+ is an array of two or more elements,
-- 
cgit v1.2.3