From 2156979340acca7437d2aeccaa4b4876459c05f6 Mon Sep 17 00:00:00 2001
From: BurdetteLamar <burdettelamar@yahoo.com>
Date: Fri, 2 Dec 2022 13:43:04 +0000
Subject: [PATCH 1/3] Enhanced RDoc for Net::HTTP

---
 lib/net/http/request.rb  |  38 ++--
 lib/net/http/requests.rb | 425 ++++++++++++++++++++++++++++++++++++---
 2 files changed, 422 insertions(+), 41 deletions(-)

diff --git a/lib/net/http/request.rb b/lib/net/http/request.rb
index 279316e0..f3d32edb 100644
--- a/lib/net/http/request.rb
+++ b/lib/net/http/request.rb
@@ -4,23 +4,28 @@
 # it wraps together the request path and the request headers.
 #
 # The class should not be used directly;
-# instead you should use its subclasses:
+# instead you should use its subclasses.
 #
-# - \Net::HTTP::Get
-# - \Net::HTTP::Head
-# - \Net::HTTP::Post
-# - \Net::HTTP::Delete
-# - \Net::HTTP::Options
-# - \Net::HTTP::Trace
-# - \Net::HTTP::Patch
-# - \Net::HTTP::Put
-# - \Net::HTTP::Copy
-# - \Net::HTTP::Lock
-# - \Net::HTTP::Mkcol
-# - \Net::HTTP::Move
-# - \Net::HTTP::Propfind
-# - \Net::HTTP::Proppatch
-# - \Net::HTTP::Unlock
+# Subclasses for HTTP requests:
+#
+# - Net::HTTP::Get
+# - Net::HTTP::Head
+# - Net::HTTP::Post
+# - Net::HTTP::Put
+# - Net::HTTP::Delete
+# - Net::HTTP::Options
+# - Net::HTTP::Trace
+# - Net::HTTP::Patch
+#
+# Subclasses for WebDAV requests:
+#
+# - Net::HTTP::Propfind
+# - Net::HTTP::Proppatch
+# - Net::HTTP::Mkcol
+# - Net::HTTP::Copy
+# - Net::HTTP::Move
+# - Net::HTTP::Lock
+# - Net::HTTP::Unlock
 #
 class Net::HTTPRequest < Net::HTTPGenericRequest
   # Creates an HTTP request object for +path+.
@@ -36,4 +41,3 @@ def initialize(path, initheader = nil)
           path, initheader
   end
 end
-
diff --git a/lib/net/http/requests.rb b/lib/net/http/requests.rb
index d4c80a38..af554cbf 100644
--- a/lib/net/http/requests.rb
+++ b/lib/net/http/requests.rb
@@ -1,67 +1,318 @@
 # frozen_string_literal: false
-#
+
 # HTTP/1.1 methods --- RFC2616
-#
 
-# See Net::HTTPGenericRequest for attributes and methods.
-# See Net::HTTP for usage examples.
+# \Class for representing
+# {HTTP method GET}[https://en.wikipedia.org/w/index.php?title=Hypertext_Transfer_Protocol#GET_method]:
+#
+#   require 'net/http'
+#   uri = URI('https://jsonplaceholder.typicode.com')
+#   hostname = uri.hostname # => "jsonplaceholder.typicode.com"
+#
+#   req = Net::HTTP::Get.new(uri) # => #<Net::HTTP::Get GET>
+#   # Default headers.
+#   req.to_hash
+#   # =>
+#   {"accept-encoding"=>["gzip;q=1.0,deflate;q=0.6,identity;q=0.3"],
+#    "accept"=>["*/*"],
+#    "user-agent"=>["Ruby"],
+#    "host"=>["jsonplaceholder.typicode.com"]}
+#
+#   res = Net::HTTP.start(hostname) do |http|
+#     http.request(req)
+#   end
+#
+# Properties:
+#
+# - Request body: optional.
+# - Response body: yes.
+# - {Safe}[https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol#Safe_methods]: yes.
+# - {Idempotent}[https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol#Idempotent_methods]: yes.
+# - {Cacheable}[https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol#Cacheable_methods]: yes.
+#
+# Related:
+#
+# - Net::HTTP.get: sends +GET+ request, returns response body.
+# - Net::HTTP#get: sends +GET+ request, returns response object.
+#
 class Net::HTTP::Get < Net::HTTPRequest
   METHOD = 'GET'
   REQUEST_HAS_BODY  = false
   RESPONSE_HAS_BODY = true
 end
 
-# See Net::HTTPGenericRequest for attributes and methods.
-# See Net::HTTP for usage examples.
+# \Class for representing
+# {HTTP method HEAD}[https://en.wikipedia.org/w/index.php?title=Hypertext_Transfer_Protocol#HEAD_method]:
+#
+#   require 'net/http'
+#   uri = URI('https://jsonplaceholder.typicode.com')
+#   hostname = uri.hostname # => "jsonplaceholder.typicode.com"
+#
+#   req = Net::HTTP::Head.new(uri) # => #<Net::HTTP::Head HEAD>
+#   # Default headers.
+#   req.to_hash
+#   # =>
+#   {"accept-encoding"=>["gzip;q=1.0,deflate;q=0.6,identity;q=0.3"],
+#    "accept"=>["*/*"],
+#    "user-agent"=>["Ruby"],
+#    "host"=>["jsonplaceholder.typicode.com"]}
+#
+#   res = Net::HTTP.start(hostname) do |http|
+#     http.request(req)
+#   end
+#
+# Properties:
+#
+# - Request body: optional.
+# - Response body: no.
+# - {Safe}[https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol#Safe_methods]: yes.
+# - {Idempotent}[https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol#Idempotent_methods]: yes.
+# - {Cacheable}[https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol#Cacheable_methods]: yes.
+#
+# Related:
+#
+# - Net::HTTP.head: sends +HEAD+ request, returns response object.
+# - Net::HTTP#head: sends +HEAD+ request, returns response object.
+#
 class Net::HTTP::Head < Net::HTTPRequest
   METHOD = 'HEAD'
   REQUEST_HAS_BODY = false
   RESPONSE_HAS_BODY = false
 end
 
-# See Net::HTTPGenericRequest for attributes and methods.
-# See Net::HTTP for usage examples.
+# \Class for representing
+# {HTTP method POST}[https://en.wikipedia.org/w/index.php?title=Hypertext_Transfer_Protocol#POST_method]:
+#
+#   require 'net/http'
+#   uri = URI('https://jsonplaceholder.typicode.com')
+#   hostname = uri.hostname # => "jsonplaceholder.typicode.com"
+#
+#   uri.path = '/posts'
+#   req = Net::HTTP::Post.new(uri) # => #<Net::HTTP::Post POST>
+#   # Default headers.
+#   req.to_hash
+#   # =>
+#   {"accept-encoding"=>["gzip;q=1.0,deflate;q=0.6,identity;q=0.3"],
+#    "accept"=>["*/*"],
+#    "user-agent"=>["Ruby"],
+#    "host"=>["jsonplaceholder.typicode.com"]}
+#
+#   req.body = '{"title": "foo","body": "bar","userId": 1}'
+#   req.content_type = 'application/json'
+#   res = Net::HTTP.start(hostname) do |http|
+#     http.request(req)
+#   end
+#
+# Properties:
+#
+# - Request body: yes.
+# - Response body: yes.
+# - {Safe}[https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol#Safe_methods]: no.
+# - {Idempotent}[https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol#Idempotent_methods]: no.
+# - {Cacheable}[https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol#Cacheable_methods]: yes.
+#
+# Related:
+#
+# - Net::HTTP.post: sends +POST+ request, returns response object.
+# - Net::HTTP#post: sends +POST+ request, returns response object.
+#
 class Net::HTTP::Post < Net::HTTPRequest
   METHOD = 'POST'
   REQUEST_HAS_BODY = true
   RESPONSE_HAS_BODY = true
 end
 
-# See Net::HTTPGenericRequest for attributes and methods.
-# See Net::HTTP for usage examples.
+# \Class for representing
+# {HTTP method PUT}[https://en.wikipedia.org/w/index.php?title=Hypertext_Transfer_Protocol#PUT_method]:
+#
+#   require 'net/http'
+#   uri = URI('https://jsonplaceholder.typicode.com')
+#   hostname = uri.hostname # => "jsonplaceholder.typicode.com"
+#
+#   uri.path = '/posts'
+#   req = Net::HTTP::Put.new(uri) # => #<Net::HTTP::Put PUT>
+#   # Default headers.
+#   req.to_hash
+#   # =>
+#   {"accept-encoding"=>["gzip;q=1.0,deflate;q=0.6,identity;q=0.3"],
+#    "accept"=>["*/*"],
+#    "user-agent"=>["Ruby"],
+#    "host"=>["jsonplaceholder.typicode.com"]}
+#
+#   req.body = '{"title": "foo","body": "bar","userId": 1}'
+#   req.content_type = 'application/json'
+#   res = Net::HTTP.start(hostname) do |http|
+#     http.request(req)
+#   end
+#
+# Properties:
+#
+# - Request body: yes.
+# - Response body: yes.
+# - {Safe}[https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol#Safe_methods]: no.
+# - {Idempotent}[https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol#Idempotent_methods]: yes.
+# - {Cacheable}[https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol#Cacheable_methods]: no.
+#
 class Net::HTTP::Put < Net::HTTPRequest
   METHOD = 'PUT'
   REQUEST_HAS_BODY = true
   RESPONSE_HAS_BODY = true
 end
 
-# See Net::HTTPGenericRequest for attributes and methods.
-# See Net::HTTP for usage examples.
+# \Class for representing
+# {HTTP method DELETE}[https://en.wikipedia.org/w/index.php?title=Hypertext_Transfer_Protocol#DELETE_method]:
+#
+#   require 'net/http'
+#   uri = URI('https://jsonplaceholder.typicode.com')
+#   hostname = uri.hostname # => "jsonplaceholder.typicode.com"
+#
+#   uri.path = '/posts/1'
+#   req = Net::HTTP::Delete.new(uri) # => #<Net::HTTP::Delete DELETE>
+#   # Default headers.
+#   req.to_hash
+#   # =>
+#   {"accept-encoding"=>["gzip;q=1.0,deflate;q=0.6,identity;q=0.3"],
+#    "accept"=>["*/*"],
+#    "user-agent"=>["Ruby"],
+#    "host"=>["jsonplaceholder.typicode.com"]}
+#
+#   res = Net::HTTP.start(hostname) do |http|
+#     http.request(req)
+#   end
+#
+# Properties:
+#
+# - Request body: optional.
+# - Response body: yes.
+# - {Safe}[https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol#Safe_methods]: no.
+# - {Idempotent}[https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol#Idempotent_methods]: yes.
+# - {Cacheable}[https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol#Cacheable_methods]: no.
+#
+# Related:
+#
+# - Net::HTTP.delete: sends +DELETE+ request, returns response object.
+# - Net::HTTP#delete: sends +DELETE+ request, returns response object.
+#
 class Net::HTTP::Delete < Net::HTTPRequest
   METHOD = 'DELETE'
   REQUEST_HAS_BODY = false
   RESPONSE_HAS_BODY = true
 end
 
-# See Net::HTTPGenericRequest for attributes and methods.
+# \Class for representing
+# {HTTP method OPTIONS}[https://en.wikipedia.org/w/index.php?title=Hypertext_Transfer_Protocol#OPTIONS_method]:
+#
+#   require 'net/http'
+#   uri = URI('https://jsonplaceholder.typicode.com')
+#   hostname = uri.hostname # => "jsonplaceholder.typicode.com"
+#
+#   req = Net::HTTP::Options.new(uri) # => #<Net::HTTP::Options OPTIONS>
+#   # Default headers.
+#   req.to_hash
+#   # =>
+#   {"accept-encoding"=>["gzip;q=1.0,deflate;q=0.6,identity;q=0.3"],
+#    "accept"=>["*/*"],
+#    "user-agent"=>["Ruby"],
+#    "host"=>["jsonplaceholder.typicode.com"]}
+#
+#   res = Net::HTTP.start(hostname) do |http|
+#     http.request(req)
+#   end
+#
+# Properties:
+#
+# - Request body: optional.
+# - Response body: yes.
+# - {Safe}[https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol#Safe_methods]: yes.
+# - {Idempotent}[https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol#Idempotent_methods]: yes.
+# - {Cacheable}[https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol#Cacheable_methods]: no.
+#
+# Related:
+#
+# - Net::HTTP.options: sends +OPTIONS+ request, returns response object.
+# - Net::HTTP#options: sends +OPTIONS+ request, returns response object.
+#
 class Net::HTTP::Options < Net::HTTPRequest
   METHOD = 'OPTIONS'
   REQUEST_HAS_BODY = false
   RESPONSE_HAS_BODY = true
 end
 
-# See Net::HTTPGenericRequest for attributes and methods.
+# \Class for representing
+# {HTTP method TRACE}[https://en.wikipedia.org/w/index.php?title=Hypertext_Transfer_Protocol#TRACE_method]:
+#
+#   require 'net/http'
+#   uri = URI('https://jsonplaceholder.typicode.com')
+#   hostname = uri.hostname # => "jsonplaceholder.typicode.com"
+#
+#   req = Net::HTTP::Trace.new(uri) # => #<Net::HTTP::Trace TRACE>
+#   # Default headers.
+#   req.to_hash
+#   # =>
+#   {"accept-encoding"=>["gzip;q=1.0,deflate;q=0.6,identity;q=0.3"],
+#    "accept"=>["*/*"],
+#    "user-agent"=>["Ruby"],
+#    "host"=>["jsonplaceholder.typicode.com"]}
+#
+#   res = Net::HTTP.start(hostname) do |http|
+#     http.request(req)
+#   end
+#
+# Properties:
+#
+# - Request body: no.
+# - Response body: yes.
+# - {Safe}[https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol#Safe_methods]: yes.
+# - {Idempotent}[https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol#Idempotent_methods]: yes.
+# - {Cacheable}[https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol#Cacheable_methods]: no.
+#
+# Related:
+#
+# - Net::HTTP.trace: sends +TRACE+ request, returns response object.
+# - Net::HTTP#trace: sends +TRACE+ request, returns response object.
+#
 class Net::HTTP::Trace < Net::HTTPRequest
   METHOD = 'TRACE'
   REQUEST_HAS_BODY = false
   RESPONSE_HAS_BODY = true
 end
 
+# \Class for representing
+# {HTTP method PATCH}[https://en.wikipedia.org/w/index.php?title=Hypertext_Transfer_Protocol#PATCH_method]:
 #
-# PATCH method --- RFC5789
+#   require 'net/http'
+#   uri = URI('https://jsonplaceholder.typicode.com')
+#   hostname = uri.hostname # => "jsonplaceholder.typicode.com"
+#
+#   uri.path = '/posts'
+#   req = Net::HTTP::Patch.new(uri) # => #<Net::HTTP::Patch PATCH>
+#   # Default headers.
+#   req.to_hash
+#   # =>
+#   {"accept-encoding"=>["gzip;q=1.0,deflate;q=0.6,identity;q=0.3"],
+#    "accept"=>["*/*"],
+#    "user-agent"=>["Ruby"],
+#    "host"=>["jsonplaceholder.typicode.com"]}
+#
+#   req.body = '{"title": "foo","body": "bar","userId": 1}'
+#   req.content_type = 'application/json'
+#   res = Net::HTTP.start(hostname) do |http|
+#     http.request(req)
+#   end
+#
+# Properties:
+#
+# - Request body: yes.
+# - Response body: yes.
+# - {Safe}[https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol#Safe_methods]: no.
+# - {Idempotent}[https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol#Idempotent_methods]: no.
+# - {Cacheable}[https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol#Cacheable_methods]: no.
+#
+# Related:
+#
+# - Net::HTTP.patch: sends +PATCH+ request, returns response object.
+# - Net::HTTP#patch: sends +PATCH+ request, returns response object.
 #
-
-# See Net::HTTPGenericRequest for attributes and methods.
 class Net::HTTP::Patch < Net::HTTPRequest
   METHOD = 'PATCH'
   REQUEST_HAS_BODY = true
@@ -72,49 +323,175 @@ class Net::HTTP::Patch < Net::HTTPRequest
 # WebDAV methods --- RFC2518
 #
 
-# See Net::HTTPGenericRequest for attributes and methods.
+# \Class for representing
+# {WebDAV method PROPFIND}[http://www.webdav.org/specs/rfc4918.html#METHOD_PROPFIND]:
+#
+#   require 'net/http'
+#   uri = URI('https://jsonplaceholder.typicode.com')
+#
+#   req = Net::HTTP::Propfind.new(uri) # => #<Net::HTTP::Propfind PROPFIND>
+#   # Default headers.
+#   req.to_hash
+#   # =>
+#   {"accept-encoding"=>["gzip;q=1.0,deflate;q=0.6,identity;q=0.3"],
+#    "accept"=>["*/*"],
+#    "user-agent"=>["Ruby"],
+#    "host"=>["jsonplaceholder.typicode.com"]}
+#
+# Related:
+#
+# - Net::HTTP#propfind: sends +PROPFIND+ request, returns response object.
+#
 class Net::HTTP::Propfind < Net::HTTPRequest
   METHOD = 'PROPFIND'
   REQUEST_HAS_BODY = true
   RESPONSE_HAS_BODY = true
 end
 
-# See Net::HTTPGenericRequest for attributes and methods.
+# \Class for representing
+# {WebDAV method PROPPATCH}[http://www.webdav.org/specs/rfc4918.html#METHOD_PROPPATCH]:
+#
+#   require 'net/http'
+#   uri = URI('https://jsonplaceholder.typicode.com')
+#
+#   req = Net::HTTP::Proppatch.new(uri) # => #<Net::HTTP::Proppatch PROPPATCH>
+#   # Default headers.
+#   req.to_hash
+#   # =>
+#   {"accept-encoding"=>["gzip;q=1.0,deflate;q=0.6,identity;q=0.3"],
+#    "accept"=>["*/*"],
+#    "user-agent"=>["Ruby"],
+#    "host"=>["jsonplaceholder.typicode.com"]}
+#
+# Related:
+#
+# - Net::HTTP#proppatch: sends +PROPPATCH+ request, returns response object.
+#
 class Net::HTTP::Proppatch < Net::HTTPRequest
   METHOD = 'PROPPATCH'
   REQUEST_HAS_BODY = true
   RESPONSE_HAS_BODY = true
 end
 
-# See Net::HTTPGenericRequest for attributes and methods.
+# \Class for representing
+# {WebDAV method MKCOL}[http://www.webdav.org/specs/rfc4918.html#METHOD_MKCOL]:
+#
+#   require 'net/http'
+#   uri = URI('https://jsonplaceholder.typicode.com')
+#
+#   req = Net::HTTP::Mkcol.new(uri) # => #<Net::HTTP::Mkcol MKCOL>
+#   # Default headers.
+#   req.to_hash
+#   # =>
+#   {"accept-encoding"=>["gzip;q=1.0,deflate;q=0.6,identity;q=0.3"],
+#    "accept"=>["*/*"],
+#    "user-agent"=>["Ruby"],
+#    "host"=>["jsonplaceholder.typicode.com"]}
+#
+# Related:
+#
+# - Net::HTTP#mkcol: sends +MKCOL+ request, returns response object.
+#
 class Net::HTTP::Mkcol < Net::HTTPRequest
   METHOD = 'MKCOL'
   REQUEST_HAS_BODY = true
   RESPONSE_HAS_BODY = true
 end
 
-# See Net::HTTPGenericRequest for attributes and methods.
+# \Class for representing
+# {WebDAV method COPY}[http://www.webdav.org/specs/rfc4918.html#METHOD_COPY]:
+#
+#   require 'net/http'
+#   uri = URI('https://jsonplaceholder.typicode.com')
+#
+#   req = Net::HTTP::Copy.new(uri) # => #<Net::HTTP::Copy COPY>
+#   # Default headers.
+#   req.to_hash
+#   # =>
+#   {"accept-encoding"=>["gzip;q=1.0,deflate;q=0.6,identity;q=0.3"],
+#    "accept"=>["*/*"],
+#    "user-agent"=>["Ruby"],
+#    "host"=>["jsonplaceholder.typicode.com"]}
+#
+# Related:
+#
+# - Net::HTTP#copy: sends +COPY+ request, returns response object.
+#
 class Net::HTTP::Copy < Net::HTTPRequest
   METHOD = 'COPY'
   REQUEST_HAS_BODY = false
   RESPONSE_HAS_BODY = true
 end
 
-# See Net::HTTPGenericRequest for attributes and methods.
+# \Class for representing
+# {WebDAV method MOVE}[http://www.webdav.org/specs/rfc4918.html#METHOD_MOVE]:
+#
+#   require 'net/http'
+#   uri = URI('https://jsonplaceholder.typicode.com')
+#
+#   req = Net::HTTP::Move.new(uri) # => #<Net::HTTP::Move MOVE>
+#   # Default headers.
+#   req.to_hash
+#   # =>
+#   {"accept-encoding"=>["gzip;q=1.0,deflate;q=0.6,identity;q=0.3"],
+#    "accept"=>["*/*"],
+#    "user-agent"=>["Ruby"],
+#    "host"=>["jsonplaceholder.typicode.com"]}
+#
+# Related:
+#
+# - Net::HTTP#move: sends +MOVE+ request, returns response object.
+#
 class Net::HTTP::Move < Net::HTTPRequest
   METHOD = 'MOVE'
   REQUEST_HAS_BODY = false
   RESPONSE_HAS_BODY = true
 end
 
-# See Net::HTTPGenericRequest for attributes and methods.
+# \Class for representing
+# {WebDAV method LOCK}[http://www.webdav.org/specs/rfc4918.html#METHOD_LOCK]:
+#
+#   require 'net/http'
+#   uri = URI('https://jsonplaceholder.typicode.com')
+#
+#   req = Net::HTTP::Lock.new(uri) # => #<Net::HTTP::Lock LOCK>
+#   # Default headers.
+#   req.to_hash
+#   # =>
+#   {"accept-encoding"=>["gzip;q=1.0,deflate;q=0.6,identity;q=0.3"],
+#    "accept"=>["*/*"],
+#    "user-agent"=>["Ruby"],
+#    "host"=>["jsonplaceholder.typicode.com"]}
+#
+# Related:
+#
+# - Net::HTTP#lock: sends +LOCK+ request, returns response object.
+#
 class Net::HTTP::Lock < Net::HTTPRequest
   METHOD = 'LOCK'
   REQUEST_HAS_BODY = true
   RESPONSE_HAS_BODY = true
 end
 
-# See Net::HTTPGenericRequest for attributes and methods.
+# \Class for representing
+# {WebDAV method UNLOCK}[http://www.webdav.org/specs/rfc4918.html#METHOD_UNLOCK]:
+#
+#   require 'net/http'
+#   uri = URI('https://jsonplaceholder.typicode.com')
+#
+#   req = Net::HTTP::Unlock.new(uri) # => #<Net::HTTP::Unlock UNLOCK>
+#   # Default headers.
+#   req.to_hash
+#   # =>
+#   {"accept-encoding"=>["gzip;q=1.0,deflate;q=0.6,identity;q=0.3"],
+#    "accept"=>["*/*"],
+#    "user-agent"=>["Ruby"],
+#    "host"=>["jsonplaceholder.typicode.com"]}
+#
+# Related:
+#
+# - Net::HTTP#unlock: sends +UNLOCK+ request, returns response object.
+#
 class Net::HTTP::Unlock < Net::HTTPRequest
   METHOD = 'UNLOCK'
   REQUEST_HAS_BODY = true

From a5bfcdd56607e6a8315383ad4df56f06248f6a12 Mon Sep 17 00:00:00 2001
From: BurdetteLamar <burdettelamar@yahoo.com>
Date: Sat, 3 Dec 2022 20:38:42 +0000
Subject: [PATCH 2/3] Enhanced RDoc for Net::HTTP

---
 lib/net/http/requests.rb | 202 ++++++++++-----------------------------
 1 file changed, 51 insertions(+), 151 deletions(-)

diff --git a/lib/net/http/requests.rb b/lib/net/http/requests.rb
index af554cbf..375a7e47 100644
--- a/lib/net/http/requests.rb
+++ b/lib/net/http/requests.rb
@@ -6,18 +6,9 @@
 # {HTTP method GET}[https://en.wikipedia.org/w/index.php?title=Hypertext_Transfer_Protocol#GET_method]:
 #
 #   require 'net/http'
-#   uri = URI('https://jsonplaceholder.typicode.com')
-#   hostname = uri.hostname # => "jsonplaceholder.typicode.com"
-#
+#   uri = URI('http://example.com')
+#   hostname = uri.hostname # => "example.com"
 #   req = Net::HTTP::Get.new(uri) # => #<Net::HTTP::Get GET>
-#   # Default headers.
-#   req.to_hash
-#   # =>
-#   {"accept-encoding"=>["gzip;q=1.0,deflate;q=0.6,identity;q=0.3"],
-#    "accept"=>["*/*"],
-#    "user-agent"=>["Ruby"],
-#    "host"=>["jsonplaceholder.typicode.com"]}
-#
 #   res = Net::HTTP.start(hostname) do |http|
 #     http.request(req)
 #   end
@@ -45,18 +36,9 @@ class Net::HTTP::Get < Net::HTTPRequest
 # {HTTP method HEAD}[https://en.wikipedia.org/w/index.php?title=Hypertext_Transfer_Protocol#HEAD_method]:
 #
 #   require 'net/http'
-#   uri = URI('https://jsonplaceholder.typicode.com')
-#   hostname = uri.hostname # => "jsonplaceholder.typicode.com"
-#
+#   uri = URI('http://example.com')
+#   hostname = uri.hostname # => "example.com"
 #   req = Net::HTTP::Head.new(uri) # => #<Net::HTTP::Head HEAD>
-#   # Default headers.
-#   req.to_hash
-#   # =>
-#   {"accept-encoding"=>["gzip;q=1.0,deflate;q=0.6,identity;q=0.3"],
-#    "accept"=>["*/*"],
-#    "user-agent"=>["Ruby"],
-#    "host"=>["jsonplaceholder.typicode.com"]}
-#
 #   res = Net::HTTP.start(hostname) do |http|
 #     http.request(req)
 #   end
@@ -84,19 +66,10 @@ class Net::HTTP::Head < Net::HTTPRequest
 # {HTTP method POST}[https://en.wikipedia.org/w/index.php?title=Hypertext_Transfer_Protocol#POST_method]:
 #
 #   require 'net/http'
-#   uri = URI('https://jsonplaceholder.typicode.com')
-#   hostname = uri.hostname # => "jsonplaceholder.typicode.com"
-#
+#   uri = URI('http://example.com')
+#   hostname = uri.hostname # => "example.com"
 #   uri.path = '/posts'
 #   req = Net::HTTP::Post.new(uri) # => #<Net::HTTP::Post POST>
-#   # Default headers.
-#   req.to_hash
-#   # =>
-#   {"accept-encoding"=>["gzip;q=1.0,deflate;q=0.6,identity;q=0.3"],
-#    "accept"=>["*/*"],
-#    "user-agent"=>["Ruby"],
-#    "host"=>["jsonplaceholder.typicode.com"]}
-#
 #   req.body = '{"title": "foo","body": "bar","userId": 1}'
 #   req.content_type = 'application/json'
 #   res = Net::HTTP.start(hostname) do |http|
@@ -126,19 +99,10 @@ class Net::HTTP::Post < Net::HTTPRequest
 # {HTTP method PUT}[https://en.wikipedia.org/w/index.php?title=Hypertext_Transfer_Protocol#PUT_method]:
 #
 #   require 'net/http'
-#   uri = URI('https://jsonplaceholder.typicode.com')
-#   hostname = uri.hostname # => "jsonplaceholder.typicode.com"
-#
+#   uri = URI('http://example.com')
+#   hostname = uri.hostname # => "example.com"
 #   uri.path = '/posts'
 #   req = Net::HTTP::Put.new(uri) # => #<Net::HTTP::Put PUT>
-#   # Default headers.
-#   req.to_hash
-#   # =>
-#   {"accept-encoding"=>["gzip;q=1.0,deflate;q=0.6,identity;q=0.3"],
-#    "accept"=>["*/*"],
-#    "user-agent"=>["Ruby"],
-#    "host"=>["jsonplaceholder.typicode.com"]}
-#
 #   req.body = '{"title": "foo","body": "bar","userId": 1}'
 #   req.content_type = 'application/json'
 #   res = Net::HTTP.start(hostname) do |http|
@@ -163,19 +127,10 @@ class Net::HTTP::Put < Net::HTTPRequest
 # {HTTP method DELETE}[https://en.wikipedia.org/w/index.php?title=Hypertext_Transfer_Protocol#DELETE_method]:
 #
 #   require 'net/http'
-#   uri = URI('https://jsonplaceholder.typicode.com')
-#   hostname = uri.hostname # => "jsonplaceholder.typicode.com"
-#
+#   uri = URI('http://example.com')
+#   hostname = uri.hostname # => "example.com"
 #   uri.path = '/posts/1'
 #   req = Net::HTTP::Delete.new(uri) # => #<Net::HTTP::Delete DELETE>
-#   # Default headers.
-#   req.to_hash
-#   # =>
-#   {"accept-encoding"=>["gzip;q=1.0,deflate;q=0.6,identity;q=0.3"],
-#    "accept"=>["*/*"],
-#    "user-agent"=>["Ruby"],
-#    "host"=>["jsonplaceholder.typicode.com"]}
-#
 #   res = Net::HTTP.start(hostname) do |http|
 #     http.request(req)
 #   end
@@ -203,18 +158,9 @@ class Net::HTTP::Delete < Net::HTTPRequest
 # {HTTP method OPTIONS}[https://en.wikipedia.org/w/index.php?title=Hypertext_Transfer_Protocol#OPTIONS_method]:
 #
 #   require 'net/http'
-#   uri = URI('https://jsonplaceholder.typicode.com')
-#   hostname = uri.hostname # => "jsonplaceholder.typicode.com"
-#
+#   uri = URI('http://example.com')
+#   hostname = uri.hostname # => "example.com"
 #   req = Net::HTTP::Options.new(uri) # => #<Net::HTTP::Options OPTIONS>
-#   # Default headers.
-#   req.to_hash
-#   # =>
-#   {"accept-encoding"=>["gzip;q=1.0,deflate;q=0.6,identity;q=0.3"],
-#    "accept"=>["*/*"],
-#    "user-agent"=>["Ruby"],
-#    "host"=>["jsonplaceholder.typicode.com"]}
-#
 #   res = Net::HTTP.start(hostname) do |http|
 #     http.request(req)
 #   end
@@ -242,18 +188,9 @@ class Net::HTTP::Options < Net::HTTPRequest
 # {HTTP method TRACE}[https://en.wikipedia.org/w/index.php?title=Hypertext_Transfer_Protocol#TRACE_method]:
 #
 #   require 'net/http'
-#   uri = URI('https://jsonplaceholder.typicode.com')
-#   hostname = uri.hostname # => "jsonplaceholder.typicode.com"
-#
+#   uri = URI('http://example.com')
+#   hostname = uri.hostname # => "example.com"
 #   req = Net::HTTP::Trace.new(uri) # => #<Net::HTTP::Trace TRACE>
-#   # Default headers.
-#   req.to_hash
-#   # =>
-#   {"accept-encoding"=>["gzip;q=1.0,deflate;q=0.6,identity;q=0.3"],
-#    "accept"=>["*/*"],
-#    "user-agent"=>["Ruby"],
-#    "host"=>["jsonplaceholder.typicode.com"]}
-#
 #   res = Net::HTTP.start(hostname) do |http|
 #     http.request(req)
 #   end
@@ -281,19 +218,10 @@ class Net::HTTP::Trace < Net::HTTPRequest
 # {HTTP method PATCH}[https://en.wikipedia.org/w/index.php?title=Hypertext_Transfer_Protocol#PATCH_method]:
 #
 #   require 'net/http'
-#   uri = URI('https://jsonplaceholder.typicode.com')
-#   hostname = uri.hostname # => "jsonplaceholder.typicode.com"
-#
+#   uri = URI('http://example.com')
+#   hostname = uri.hostname # => "example.com"
 #   uri.path = '/posts'
 #   req = Net::HTTP::Patch.new(uri) # => #<Net::HTTP::Patch PATCH>
-#   # Default headers.
-#   req.to_hash
-#   # =>
-#   {"accept-encoding"=>["gzip;q=1.0,deflate;q=0.6,identity;q=0.3"],
-#    "accept"=>["*/*"],
-#    "user-agent"=>["Ruby"],
-#    "host"=>["jsonplaceholder.typicode.com"]}
-#
 #   req.body = '{"title": "foo","body": "bar","userId": 1}'
 #   req.content_type = 'application/json'
 #   res = Net::HTTP.start(hostname) do |http|
@@ -327,16 +255,12 @@ class Net::HTTP::Patch < Net::HTTPRequest
 # {WebDAV method PROPFIND}[http://www.webdav.org/specs/rfc4918.html#METHOD_PROPFIND]:
 #
 #   require 'net/http'
-#   uri = URI('https://jsonplaceholder.typicode.com')
-#
+#   uri = URI('http://example.com')
+#   hostname = uri.hostname # => "example.com"
 #   req = Net::HTTP::Propfind.new(uri) # => #<Net::HTTP::Propfind PROPFIND>
-#   # Default headers.
-#   req.to_hash
-#   # =>
-#   {"accept-encoding"=>["gzip;q=1.0,deflate;q=0.6,identity;q=0.3"],
-#    "accept"=>["*/*"],
-#    "user-agent"=>["Ruby"],
-#    "host"=>["jsonplaceholder.typicode.com"]}
+#   res = Net::HTTP.start(hostname) do |http|
+#     http.request(req)
+#   end
 #
 # Related:
 #
@@ -352,16 +276,12 @@ class Net::HTTP::Propfind < Net::HTTPRequest
 # {WebDAV method PROPPATCH}[http://www.webdav.org/specs/rfc4918.html#METHOD_PROPPATCH]:
 #
 #   require 'net/http'
-#   uri = URI('https://jsonplaceholder.typicode.com')
-#
+#   uri = URI('http://example.com')
+#   hostname = uri.hostname # => "example.com"
 #   req = Net::HTTP::Proppatch.new(uri) # => #<Net::HTTP::Proppatch PROPPATCH>
-#   # Default headers.
-#   req.to_hash
-#   # =>
-#   {"accept-encoding"=>["gzip;q=1.0,deflate;q=0.6,identity;q=0.3"],
-#    "accept"=>["*/*"],
-#    "user-agent"=>["Ruby"],
-#    "host"=>["jsonplaceholder.typicode.com"]}
+#   res = Net::HTTP.start(hostname) do |http|
+#     http.request(req)
+#   end
 #
 # Related:
 #
@@ -377,16 +297,12 @@ class Net::HTTP::Proppatch < Net::HTTPRequest
 # {WebDAV method MKCOL}[http://www.webdav.org/specs/rfc4918.html#METHOD_MKCOL]:
 #
 #   require 'net/http'
-#   uri = URI('https://jsonplaceholder.typicode.com')
-#
+#   uri = URI('http://example.com')
+#   hostname = uri.hostname # => "example.com"
 #   req = Net::HTTP::Mkcol.new(uri) # => #<Net::HTTP::Mkcol MKCOL>
-#   # Default headers.
-#   req.to_hash
-#   # =>
-#   {"accept-encoding"=>["gzip;q=1.0,deflate;q=0.6,identity;q=0.3"],
-#    "accept"=>["*/*"],
-#    "user-agent"=>["Ruby"],
-#    "host"=>["jsonplaceholder.typicode.com"]}
+#   res = Net::HTTP.start(hostname) do |http|
+#     http.request(req)
+#   end
 #
 # Related:
 #
@@ -402,16 +318,12 @@ class Net::HTTP::Mkcol < Net::HTTPRequest
 # {WebDAV method COPY}[http://www.webdav.org/specs/rfc4918.html#METHOD_COPY]:
 #
 #   require 'net/http'
-#   uri = URI('https://jsonplaceholder.typicode.com')
-#
+#   uri = URI('http://example.com')
+#   hostname = uri.hostname # => "example.com"
 #   req = Net::HTTP::Copy.new(uri) # => #<Net::HTTP::Copy COPY>
-#   # Default headers.
-#   req.to_hash
-#   # =>
-#   {"accept-encoding"=>["gzip;q=1.0,deflate;q=0.6,identity;q=0.3"],
-#    "accept"=>["*/*"],
-#    "user-agent"=>["Ruby"],
-#    "host"=>["jsonplaceholder.typicode.com"]}
+#   res = Net::HTTP.start(hostname) do |http|
+#     http.request(req)
+#   end
 #
 # Related:
 #
@@ -427,16 +339,12 @@ class Net::HTTP::Copy < Net::HTTPRequest
 # {WebDAV method MOVE}[http://www.webdav.org/specs/rfc4918.html#METHOD_MOVE]:
 #
 #   require 'net/http'
-#   uri = URI('https://jsonplaceholder.typicode.com')
-#
+#   uri = URI('http://example.com')
+#   hostname = uri.hostname # => "example.com"
 #   req = Net::HTTP::Move.new(uri) # => #<Net::HTTP::Move MOVE>
-#   # Default headers.
-#   req.to_hash
-#   # =>
-#   {"accept-encoding"=>["gzip;q=1.0,deflate;q=0.6,identity;q=0.3"],
-#    "accept"=>["*/*"],
-#    "user-agent"=>["Ruby"],
-#    "host"=>["jsonplaceholder.typicode.com"]}
+#   res = Net::HTTP.start(hostname) do |http|
+#     http.request(req)
+#   end
 #
 # Related:
 #
@@ -452,16 +360,12 @@ class Net::HTTP::Move < Net::HTTPRequest
 # {WebDAV method LOCK}[http://www.webdav.org/specs/rfc4918.html#METHOD_LOCK]:
 #
 #   require 'net/http'
-#   uri = URI('https://jsonplaceholder.typicode.com')
-#
+#   uri = URI('http://example.com')
+#   hostname = uri.hostname # => "example.com"
 #   req = Net::HTTP::Lock.new(uri) # => #<Net::HTTP::Lock LOCK>
-#   # Default headers.
-#   req.to_hash
-#   # =>
-#   {"accept-encoding"=>["gzip;q=1.0,deflate;q=0.6,identity;q=0.3"],
-#    "accept"=>["*/*"],
-#    "user-agent"=>["Ruby"],
-#    "host"=>["jsonplaceholder.typicode.com"]}
+#   res = Net::HTTP.start(hostname) do |http|
+#     http.request(req)
+#   end
 #
 # Related:
 #
@@ -477,16 +381,12 @@ class Net::HTTP::Lock < Net::HTTPRequest
 # {WebDAV method UNLOCK}[http://www.webdav.org/specs/rfc4918.html#METHOD_UNLOCK]:
 #
 #   require 'net/http'
-#   uri = URI('https://jsonplaceholder.typicode.com')
-#
+#   uri = URI('http://example.com')
+#   hostname = uri.hostname # => "example.com"
 #   req = Net::HTTP::Unlock.new(uri) # => #<Net::HTTP::Unlock UNLOCK>
-#   # Default headers.
-#   req.to_hash
-#   # =>
-#   {"accept-encoding"=>["gzip;q=1.0,deflate;q=0.6,identity;q=0.3"],
-#    "accept"=>["*/*"],
-#    "user-agent"=>["Ruby"],
-#    "host"=>["jsonplaceholder.typicode.com"]}
+#   res = Net::HTTP.start(hostname) do |http|
+#     http.request(req)
+#   end
 #
 # Related:
 #

From 13558b833ee8a15a81cfad2a08e914953639d312 Mon Sep 17 00:00:00 2001
From: BurdetteLamar <burdettelamar@yahoo.com>
Date: Sun, 4 Dec 2022 19:50:43 +0000
Subject: [PATCH 3/3] Enhanced RDoc for Net::HTTP

---
 lib/net/http/requests.rb | 5 -----
 1 file changed, 5 deletions(-)

diff --git a/lib/net/http/requests.rb b/lib/net/http/requests.rb
index 375a7e47..294b8e88 100644
--- a/lib/net/http/requests.rb
+++ b/lib/net/http/requests.rb
@@ -53,7 +53,6 @@ class Net::HTTP::Get < Net::HTTPRequest
 #
 # Related:
 #
-# - Net::HTTP.head: sends +HEAD+ request, returns response object.
 # - Net::HTTP#head: sends +HEAD+ request, returns response object.
 #
 class Net::HTTP::Head < Net::HTTPRequest
@@ -145,7 +144,6 @@ class Net::HTTP::Put < Net::HTTPRequest
 #
 # Related:
 #
-# - Net::HTTP.delete: sends +DELETE+ request, returns response object.
 # - Net::HTTP#delete: sends +DELETE+ request, returns response object.
 #
 class Net::HTTP::Delete < Net::HTTPRequest
@@ -175,7 +173,6 @@ class Net::HTTP::Delete < Net::HTTPRequest
 #
 # Related:
 #
-# - Net::HTTP.options: sends +OPTIONS+ request, returns response object.
 # - Net::HTTP#options: sends +OPTIONS+ request, returns response object.
 #
 class Net::HTTP::Options < Net::HTTPRequest
@@ -205,7 +202,6 @@ class Net::HTTP::Options < Net::HTTPRequest
 #
 # Related:
 #
-# - Net::HTTP.trace: sends +TRACE+ request, returns response object.
 # - Net::HTTP#trace: sends +TRACE+ request, returns response object.
 #
 class Net::HTTP::Trace < Net::HTTPRequest
@@ -238,7 +234,6 @@ class Net::HTTP::Trace < Net::HTTPRequest
 #
 # Related:
 #
-# - Net::HTTP.patch: sends +PATCH+ request, returns response object.
 # - Net::HTTP#patch: sends +PATCH+ request, returns response object.
 #
 class Net::HTTP::Patch < Net::HTTPRequest