From a2a677937398751df21df3d54924d61fb1fbe148 Mon Sep 17 00:00:00 2001
From: BurdetteLamar <burdettelamar@yahoo.com>
Date: Thu, 5 Jan 2023 17:33:08 +0000
Subject: [PATCH 1/3] Enhanced RDoc for URI.join

---
 lib/uri/common.rb | 21 +++++----------------
 1 file changed, 5 insertions(+), 16 deletions(-)

diff --git a/lib/uri/common.rb b/lib/uri/common.rb
index c1b75c1..c63b247 100644
--- a/lib/uri/common.rb
+++ b/lib/uri/common.rb
@@ -185,23 +185,13 @@ def self.parse(uri)
     RFC3986_PARSER.parse(uri)
   end
 
+  # Recursively merges the given URI strings +str+
+  # per {RFC 2396}[https://www.rfc-editor.org/rfc/rfc2396.html].
   #
-  # == Synopsis
-  #
-  #   URI::join(str[, str, ...])
-  #
-  # == Args
-  #
-  # +str+::
-  #   String(s) to work with, will be converted to RFC3986 URIs before merging.
-  #
-  # == Description
-  #
-  # Joins URIs.
-  #
-  # == Usage
+  # Each string in +str+ is converted to an
+  # {RFC3986 URI}[https://www.rfc-editor.org/rfc/rfc3986.html] before being merged.
   #
-  #   require 'uri'
+  # Examples:
   #
   #   URI.join("http://example.com/","main.rbx")
   #   # => #<URI::HTTP http://example.com/main.rbx>
@@ -340,7 +330,6 @@ def self.regexp(schemes = nil)
   #   and then to encoding +enc+.
   #
   # In either case, the returned string has forced encoding Encoding::US_ASCII.
-  #
   def self.encode_www_form_component(str, enc=nil)
     _encode_uri_component(/[^*\-.0-9A-Z_a-z]/, TBLENCWWWCOMP_, str, enc)
   end

From a379f465f85344fca3afa362506ab02b30fa9339 Mon Sep 17 00:00:00 2001
From: BurdetteLamar <burdettelamar@yahoo.com>
Date: Thu, 5 Jan 2023 22:10:42 +0000
Subject: [PATCH 2/3] Enhanced RDoc for URI.decode_www_form_component

---
 lib/uri/common.rb | 31 ++++++++++++++++++++++++++-----
 1 file changed, 26 insertions(+), 5 deletions(-)

diff --git a/lib/uri/common.rb b/lib/uri/common.rb
index c63b247..191751e 100644
--- a/lib/uri/common.rb
+++ b/lib/uri/common.rb
@@ -236,7 +236,7 @@ def self.join(*str)
   #   URI.extract("text here http://foo.example.org/bla and here mailto:test@example.com and here also.")
   #   # => ["http://foo.example.com/bla", "mailto:test@example.com"]
   #
-  def self.extract(str, schemes = nil, &block)
+  def self.extract(str, schemes = nil, &block) # :nodoc:
     warn "URI.extract is obsolete", uplevel: 1 if $VERBOSE
     DEFAULT_PARSER.extract(str, schemes, &block)
   end
@@ -273,7 +273,7 @@ def self.extract(str, schemes = nil, &block)
   #     p $&
   #   end
   #
-  def self.regexp(schemes = nil)
+  def self.regexp(schemes = nil)# :nodoc:
     warn "URI.regexp is obsolete", uplevel: 1 if $VERBOSE
     DEFAULT_PARSER.make_regexp(schemes)
   end
@@ -334,11 +334,32 @@ def self.encode_www_form_component(str, enc=nil)
     _encode_uri_component(/[^*\-.0-9A-Z_a-z]/, TBLENCWWWCOMP_, str, enc)
   end
 
-  # Decodes given +str+ of URL-encoded form data.
+  # Returns a string derived from the given \URL-encoded string +str+.
+  # Before decoding, +str+ is force-encoded to +enc+.
   #
-  # This decodes + to SP.
+  # The returned string:
+  #
+  # - Preserves:
+  #
+  #   - Characters <tt>'*'</tt>, <tt>'.'</tt>, <tt>'-'</tt>, and <tt>'_'</tt>.
+  #   - Character in ranges <tt>'a'..'z'</tt>, <tt>'A'..'Z'</tt>,
+  #     and <tt>'0'..'9'</tt>.
+  #
+  #   Example:
+  #
+  #     URI.decode_www_form_component('*.-_azAZ09')
+  #     # => "*.-_azAZ09"
+  #
+  # - Converts:
+  #
+  #   - Character <tt>'+'</tt> to character <tt>' '</tt>.
+  #   - Each "percent notation" to an ASCII character.
+  #
+  #   Example:
+  #
+  #     URI.decode_www_form_component('Here+are+some+punctuation+characters%3A+%2C%3B%3F%3A')
+  #     # => "Here are some punctuation characters: ,;?:"
   #
-  # See URI.encode_www_form_component, URI.decode_www_form.
   def self.decode_www_form_component(str, enc=Encoding::UTF_8)
     _decode_uri_component(/\+|%\h\h/, str, enc)
   end

From e17cf88647ac187b29942ca0b64b3bdc68321621 Mon Sep 17 00:00:00 2001
From: BurdetteLamar <burdettelamar@yahoo.com>
Date: Fri, 6 Jan 2023 13:47:28 +0000
Subject: [PATCH 3/3] Enhanced RDoc for URI.decode_www_form_component

---
 lib/uri/common.rb | 8 +++++---
 1 file changed, 5 insertions(+), 3 deletions(-)

diff --git a/lib/uri/common.rb b/lib/uri/common.rb
index 191751e..54c4484 100644
--- a/lib/uri/common.rb
+++ b/lib/uri/common.rb
@@ -185,7 +185,7 @@ def self.parse(uri)
     RFC3986_PARSER.parse(uri)
   end
 
-  # Recursively merges the given URI strings +str+
+  # Merges the given URI strings +str+
   # per {RFC 2396}[https://www.rfc-editor.org/rfc/rfc2396.html].
   #
   # Each string in +str+ is converted to an
@@ -334,8 +334,10 @@ def self.encode_www_form_component(str, enc=nil)
     _encode_uri_component(/[^*\-.0-9A-Z_a-z]/, TBLENCWWWCOMP_, str, enc)
   end
 
-  # Returns a string derived from the given \URL-encoded string +str+.
-  # Before decoding, +str+ is force-encoded to +enc+.
+  # Returns a string decoded from the given \URL-encoded string +str+.
+  #
+  # The given string is first encoded as Encoding::ASCII-8BIT (using String#b),
+  # then decoded (as below), and finally force-encoded to the given encoding +enc+.
   #
   # The returned string:
   #