rbs 3.3.2 → 3.4.0.pre.1

data/stdlib/net-http/0/net-http.rbs

@@ -8,7 +8,7 @@ module Net
   # <!-- rdoc-file=lib/net/http.rb -->
   # Class Net::HTTP provides a rich library that implements the client in a
   # client-server model that uses the HTTP request-response protocol. For
-  # information about HTTP, see
+  # information about HTTP, see:
   #
   # *   [Hypertext Transfer
   #     Protocol](https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol).
@@ -17,63 +17,6 @@ module Net
   #     cal_overview).
   #
   #
-  # Note: If you are performing only a few GET requests, consider using
-  # [OpenURI](rdoc-ref:OpenURI); otherwise, read on.
-  #
-  # ## Synopsis
-  #
-  # If you are already familiar with HTTP, this synopsis may be helpful.
-  #
-  # [Session](rdoc-ref:Net::HTTP@Sessions) with multiple requests for [HTTP
-  # methods](https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol#Request_met
-  # hods):
-  #
-  #     Net::HTTP.start(hostname) do |http|
-  #       # Session started automatically before block execution.
-  #       http.get(path_or_uri, headers = {})
-  #       http.head(path_or_uri, headers = {})
-  #       http.post(path_or_uri, data, headers = {})  # Can also have a block.
-  #       http.put(path_or_uri, data, headers = {})
-  #       http.delete(path_or_uri, headers = {Depth: 'Infinity'})
-  #       http.options(path_or_uri, headers = {})
-  #       http.trace(path_or_uri, headers = {})
-  #       http.patch(path_or_uri, data, headers = {}) # Can also have a block.
-  #       # Session finished automatically at block exit.
-  #     end
-  #
-  # [Session](rdoc-ref:Net::HTTP@Sessions) with multiple requests for [WebDAV
-  # methods](https://en.wikipedia.org/wiki/WebDAV#Implementation):
-  #
-  #     Net::HTTP.start(hostname) do |http|
-  #       # Session started automatically before block execution.
-  #       http.copy(path_or_uri, headers = {})
-  #       http.lock(path_or_uri, body, headers = {})
-  #       http.mkcol(path_or_uri, body = nil, headers = {})
-  #       http.move(path_or_uri, headers = {})
-  #       http.propfind(path_or_uri, body = nil, headers = {'Depth' => '0'})
-  #       http.proppatch(path_or_uri, body, headers = {})
-  #       http.unlock(path_or_uri, body, headers = {})
-  #       # Session finished automatically at block exit.
-  #     end
-  #
-  # Each of the following methods automatically starts and finishes a
-  # [session](rdoc-ref:Net::HTTP@Sessions) that sends a single request:
-  #
-  #     # Return string response body.
-  #     Net::HTTP.get(hostname, path, port = 80)
-  #     Net::HTTP.get(uri, headers = {}, port = 80)
-  #
-  #     # Write string response body to $stdout.
-  #     Net::HTTP.get_print(hostname, path_or_uri, port = 80)
-  #     Net::HTTP.get_print(uri, headers = {}, port = 80)
-  #
-  #     # Return response as Net::HTTPResponse object.
-  #     Net::HTTP.get_response(hostname, path_or_uri, port = 80)
-  #     Net::HTTP.get_response(uri, headers = {}, port = 80)
-  #
-  #     Net::HTTP.post(uri, data, headers = {})
-  #     Net::HTTP.post_form(uri, params)
-  #
   # ## About the Examples
   #
   # Examples here assume that `net/http` has been required (which also requires
@@ -89,9 +32,10 @@ module Net
   #
   # Some examples also assume these variables:
   #
-  #     uri = URI('https://jsonplaceholder.typicode.com')
+  #     uri = URI('https://jsonplaceholder.typicode.com/')
   #     uri.freeze # Examples may not modify.
   #     hostname = uri.hostname # => "jsonplaceholder.typicode.com"
+  #     path = uri.path         # => "/"
   #     port = uri.port         # => 443
   #
   # So that example requests may be written as:
@@ -109,6 +53,64 @@ module Net
   #     _uri = uri.dup
   #     _uri.path = '/todos/1'
   #
+  # ## Strategies
+  #
+  # *   If you will make only a few GET requests, consider using
+  #     [OpenURI](rdoc-ref:OpenURI).
+  # *   If you will make only a few requests of all kinds, consider using the
+  #     various singleton convenience methods in this class. Each of the following
+  #     methods automatically starts and finishes a
+  #     [session](rdoc-ref:Net::HTTP@Sessions) that sends a single request:
+  #
+  #         # Return string response body.
+  #         Net::HTTP.get(hostname, path)
+  #         Net::HTTP.get(uri)
+  #
+  #         # Write string response body to $stdout.
+  #         Net::HTTP.get_print(hostname, path)
+  #         Net::HTTP.get_print(uri)
+  #
+  #         # Return response as Net::HTTPResponse object.
+  #         Net::HTTP.get_response(hostname, path)
+  #         Net::HTTP.get_response(uri)
+  #         data = '{"title": "foo", "body": "bar", "userId": 1}'
+  #         Net::HTTP.post(uri, data)
+  #         params = {title: 'foo', body: 'bar', userId: 1}
+  #         Net::HTTP.post_form(uri, params)
+  #
+  # *   If performance is important, consider using sessions, which lower request
+  #     overhead. This [session](rdoc-ref:Net::HTTP@Sessions) has multiple
+  #     requests for [HTTP
+  #     methods](https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol#Request
+  #     _methods) and [WebDAV
+  #     methods](https://en.wikipedia.org/wiki/WebDAV#Implementation):
+  #
+  #         Net::HTTP.start(hostname) do |http|
+  #           # Session started automatically before block execution.
+  #           http.get(path)
+  #           http.head(path)
+  #           body = 'Some text'
+  #           http.post(path, body)  # Can also have a block.
+  #           http.put(path, body)
+  #           http.delete(path)
+  #           http.options(path)
+  #           http.trace(path)
+  #           http.patch(path, body) # Can also have a block.
+  #           http.copy(path)
+  #           http.lock(path, body)
+  #           http.mkcol(path, body)
+  #           http.move(path)
+  #           http.propfind(path, body)
+  #           http.proppatch(path, body)
+  #           http.unlock(path, body)
+  #           # Session finished automatically at block exit.
+  #         end
+  #
+  #
+  # The methods cited above are convenience methods that, via their few arguments,
+  # allow minimal control over the requests. For greater control, consider using
+  # [request objects](rdoc-ref:Net::HTTPRequest).
+  #
   # ## URIs
   #
   # On the internet, a URI ([Universal Resource
@@ -184,7 +186,7 @@ module Net
   # Fields](https://en.wikipedia.org/wiki/List_of_HTTP_header_fields#Request_field
   # s). A host may also accept other custom fields.
   #
-  # ## Sessions
+  # ## HTTP Sessions
   #
   # A *session* is a connection between a server (host) and a client that:
   #
@@ -193,7 +195,7 @@ module Net
   # *   Is ended by instance method Net::HTTP#finish.
   #
   #
-  # See example sessions at the [Synopsis](rdoc-ref:Net::HTTP@Synopsis).
+  # See example sessions at [Strategies](rdoc-ref:Net::HTTP@Strategies).
   #
   # ### Session Using Net::HTTP.start
   #
@@ -284,49 +286,43 @@ module Net
   #
   # ## Following Redirection
   #
-  # Each Net::HTTPResponse object belongs to a class for its response code.
-  #
-  # For example, all 2XX responses are instances of a Net::HTTPSuccess subclass, a
-  # 3XX response is an instance of a Net::HTTPRedirection subclass and a 200
-  # response is an instance of the Net::HTTPOK class.  For details of response
-  # classes, see the section "HTTP Response Classes" below.
+  # Each returned response is an instance of a subclass of Net::HTTPResponse. See
+  # the [response class
+  # hierarchy](rdoc-ref:Net::HTTPResponse@Response+Subclasses).
   #
-  # Using a case statement you can handle various types of responses properly:
+  # In particular, class Net::HTTPRedirection is the parent of all redirection
+  # classes. This allows you to craft a case statement to handle redirections
+  # properly:
   #
-  #     def fetch(uri_str, limit = 10)
+  #     def fetch(uri, limit = 10)
   #       # You should choose a better exception.
-  #       raise ArgumentError, 'too many HTTP redirects' if limit == 0
-  #
-  #       response = Net::HTTP.get_response(URI(uri_str))
-  #
-  #       case response
-  #       when Net::HTTPSuccess then
-  #         response
-  #       when Net::HTTPRedirection then
-  #         location = response['location']
-  #         warn "redirected to #{location}"
+  #       raise ArgumentError, 'Too many HTTP redirects' if limit == 0
+  #
+  #       res = Net::HTTP.get_response(URI(uri))
+  #       case res
+  #       when Net::HTTPSuccess     # Any success class.
+  #         res
+  #       when Net::HTTPRedirection # Any redirection class.
+  #         location = res['Location']
+  #         warn "Redirected to #{location}"
   #         fetch(location, limit - 1)
-  #       else
-  #         response.value
+  #       else                      # Any other class.
+  #         res.value
   #       end
   #     end
   #
-  #     print fetch('http://www.ruby-lang.org')
+  #     fetch(uri)
   #
   # ## Basic Authentication
   #
   # Basic authentication is performed according to
-  # [RFC2617](http://www.ietf.org/rfc/rfc2617.txt).
-  #
-  #     uri = URI('http://example.com/index.html?key=value')
+  # [RFC2617](http://www.ietf.org/rfc/rfc2617.txt):
   #
   #     req = Net::HTTP::Get.new(uri)
-  #     req.basic_auth 'user', 'pass'
-  #
-  #     res = Net::HTTP.start(uri.hostname, uri.port) {|http|
+  #     req.basic_auth('user', 'pass')
+  #     res = Net::HTTP.start(hostname) do |http|
   #       http.request(req)
-  #     }
-  #     puts res.body
+  #     end
   #
   # ## Streaming Response Bodies
   #
@@ -334,15 +330,12 @@ module Net
   # handling large files or wish to implement a progress bar you can instead
   # stream the body directly to an IO.
   #
-  #     uri = URI('http://example.com/large_file')
-  #
-  #     Net::HTTP.start(uri.host, uri.port) do |http|
-  #       request = Net::HTTP::Get.new uri
-  #
-  #       http.request request do |response|
-  #         open 'large_file', 'w' do |io|
-  #           response.read_body do |chunk|
-  #             io.write chunk
+  #     Net::HTTP.start(hostname) do |http|
+  #       req = Net::HTTP::Get.new(uri)
+  #       http.request(req) do |res|
+  #         open('t.tmp', 'w') do |f|
+  #           res.read_body do |chunk|
+  #             f.write chunk
   #           end
   #         end
   #       end
@@ -350,50 +343,393 @@ module Net
   #
   # ## HTTPS
   #
-  # HTTPS is enabled for an HTTP connection by Net::HTTP#use_ssl=.
-  #
-  #     uri = URI('https://secure.example.com/some_path?query=string')
+  # HTTPS is enabled for an HTTP connection by Net::HTTP#use_ssl=:
   #
-  #     Net::HTTP.start(uri.host, uri.port, :use_ssl => true) do |http|
-  #       request = Net::HTTP::Get.new uri
-  #       response = http.request request # Net::HTTPResponse object
+  #     Net::HTTP.start(hostname, :use_ssl => true) do |http|
+  #       req = Net::HTTP::Get.new(uri)
+  #       res = http.request(req)
   #     end
   #
-  # Or if you simply want to make a GET request, you may pass in an URI object
-  # that has an HTTPS URL. Net::HTTP automatically turns on TLS verification if
-  # the URI object has a 'https' URI scheme.
+  # Or if you simply want to make a GET request, you may pass in a URI object that
+  # has an HTTPS URL. Net::HTTP automatically turns on TLS verification if the URI
+  # object has a 'https' URI scheme:
   #
-  #     uri = URI('https://example.com/')
-  #     Net::HTTP.get(uri) # => String
+  #     uri # => #<URI::HTTPS https://jsonplaceholder.typicode.com/>
+  #     Net::HTTP.get(uri)
+  #
+  # ## Proxy Server
+  #
+  # An HTTP object can have a [proxy
+  # server](https://en.wikipedia.org/wiki/Proxy_server).
+  #
+  # You can create an HTTP object with a proxy server using method Net::HTTP.new
+  # or method Net::HTTP.start.
+  #
+  # The proxy may be defined either by argument `p_addr` or by environment
+  # variable `'http_proxy'`.
+  #
+  # ### Proxy Using Argument `p_addr` as a String
+  #
+  # When argument `p_addr` is a string hostname, the returned `http` has the given
+  # host as its proxy:
+  #
+  #     http = Net::HTTP.new(hostname, nil, 'proxy.example')
+  #     http.proxy?          # => true
+  #     http.proxy_from_env? # => false
+  #     http.proxy_address   # => "proxy.example"
+  #     # These use default values.
+  #     http.proxy_port      # => 80
+  #     http.proxy_user      # => nil
+  #     http.proxy_pass      # => nil
+  #
+  # The port, username, and password for the proxy may also be given:
+  #
+  #     http = Net::HTTP.new(hostname, nil, 'proxy.example', 8000, 'pname', 'ppass')
+  #     # => #<Net::HTTP jsonplaceholder.typicode.com:80 open=false>
+  #     http.proxy?          # => true
+  #     http.proxy_from_env? # => false
+  #     http.proxy_address   # => "proxy.example"
+  #     http.proxy_port      # => 8000
+  #     http.proxy_user      # => "pname"
+  #     http.proxy_pass      # => "ppass"
+  #
+  # ### Proxy Using '`ENV['http_proxy']`'
+  #
+  # When environment variable `'http_proxy'` is set to a URI string, the returned
+  # `http` will have the server at that URI as its proxy; note that the URI string
+  # must have a protocol such as `'http'` or `'https'`:
+  #
+  #     ENV['http_proxy'] = 'http://example.com'
+  #     http = Net::HTTP.new(hostname)
+  #     http.proxy?          # => true
+  #     http.proxy_from_env? # => true
+  #     http.proxy_address   # => "example.com"
+  #     # These use default values.
+  #     http.proxy_port      # => 80
+  #     http.proxy_user      # => nil
+  #     http.proxy_pass      # => nil
+  #
+  # The URI string may include proxy username, password, and port number:
+  #
+  #     ENV['http_proxy'] = 'http://pname:ppass@example.com:8000'
+  #     http = Net::HTTP.new(hostname)
+  #     http.proxy?          # => true
+  #     http.proxy_from_env? # => true
+  #     http.proxy_address   # => "example.com"
+  #     http.proxy_port      # => 8000
+  #     http.proxy_user      # => "pname"
+  #     http.proxy_pass      # => "ppass"
+  #
+  # ### Filtering Proxies
+  #
+  # With method Net::HTTP.new (but not Net::HTTP.start), you can use argument
+  # `p_no_proxy` to filter proxies:
+  #
+  # *   Reject a certain address:
   #
-  # In previous versions of Ruby you would need to require 'net/https' to use
-  # HTTPS. This is no longer true.
+  #         http = Net::HTTP.new('example.com', nil, 'proxy.example', 8000, 'pname', 'ppass', 'proxy.example')
+  #         http.proxy_address # => nil
   #
-  # ## Proxies
+  # *   Reject certain domains or subdomains:
   #
-  # Net::HTTP will automatically create a proxy from the `http_proxy` environment
-  # variable if it is present.  To disable use of `http_proxy`, pass `nil` for the
-  # proxy address.
+  #         http = Net::HTTP.new('example.com', nil, 'my.proxy.example', 8000, 'pname', 'ppass', 'proxy.example')
+  #         http.proxy_address # => nil
   #
-  # You may also create a custom proxy:
+  # *   Reject certain addresses and port combinations:
   #
-  #     proxy_addr = 'your.proxy.host'
-  #     proxy_port = 8080
+  #         http = Net::HTTP.new('example.com', nil, 'proxy.example', 8000, 'pname', 'ppass', 'proxy.example:1234')
+  #         http.proxy_address # => "proxy.example"
   #
-  #     Net::HTTP.new('example.com', nil, proxy_addr, proxy_port).start { |http|
-  #       # always proxy via your.proxy.addr:8080
-  #     }
+  #         http = Net::HTTP.new('example.com', nil, 'proxy.example', 8000, 'pname', 'ppass', 'proxy.example:8000')
+  #         http.proxy_address # => nil
   #
-  # See Net::HTTP.new for further details and examples such as proxies that
-  # require a username and password.
+  # *   Reject a list of the types above delimited using a comma:
   #
-  # ## Compression
+  #         http = Net::HTTP.new('example.com', nil, 'proxy.example', 8000, 'pname', 'ppass', 'my.proxy,proxy.example:8000')
+  #         http.proxy_address # => nil
   #
-  # Net::HTTP automatically adds Accept-Encoding for compression of response
-  # bodies and automatically decompresses gzip and deflate responses unless a
-  # Range header was sent.
+  #         http = Net::HTTP.new('example.com', nil, 'my.proxy', 8000, 'pname', 'ppass', 'my.proxy,proxy.example:8000')
+  #         http.proxy_address # => nil
   #
-  # Compression can be disabled through the Accept-Encoding: identity header.
+  #
+  # ## Compression and Decompression
+  #
+  # Net::HTTP does not compress the body of a request before sending.
+  #
+  # By default, Net::HTTP adds header `'Accept-Encoding'` to a new [request
+  # object](rdoc-ref:Net::HTTPRequest):
+  #
+  #     Net::HTTP::Get.new(uri)['Accept-Encoding']
+  #     # => "gzip;q=1.0,deflate;q=0.6,identity;q=0.3"
+  #
+  # This requests the server to zip-encode the response body if there is one; the
+  # server is not required to do so.
+  #
+  # Net::HTTP does not automatically decompress a response body if the response
+  # has header `'Content-Range'`.
+  #
+  # Otherwise decompression (or not) depends on the value of header
+  # [Content-Encoding](https://en.wikipedia.org/wiki/List_of_HTTP_header_fields#co
+  # ntent-encoding-response-header):
+  #
+  # *   `'deflate'`, `'gzip'`, or `'x-gzip'`: decompresses the body and deletes
+  #     the header.
+  # *   `'none'` or `'identity'`: does not decompress the body, but deletes the
+  #     header.
+  # *   Any other value: leaves the body and header unchanged.
+  #
+  #
+  # ## What's Here
+  #
+  # This is a categorized summary of methods and attributes.
+  #
+  # ### Net::HTTP Objects
+  #
+  # *   [::new](rdoc-ref:Net::HTTP.new): Creates a new instance.
+  # *   [#inspect](rdoc-ref:Net::HTTP#inspect): Returns a string representation of
+  #     `self`.
+  #
+  #
+  # ### Sessions
+  #
+  # *   [::start](rdoc-ref:Net::HTTP.start): Begins a new session in a new
+  #     Net::HTTP object.
+  # *   [#started?](rdoc-ref:Net::HTTP#started?) (aliased as
+  #     [#active?](rdoc-ref:Net::HTTP#active?)): Returns whether in a session.
+  # *   [#finish](rdoc-ref:Net::HTTP#finish): Ends an active session.
+  # *   [#start](rdoc-ref:Net::HTTP#start): Begins a new session in an existing
+  #     Net::HTTP object (`self`).
+  #
+  #
+  # ### Connections
+  #
+  # *   [:continue_timeout](rdoc-ref:Net::HTTP#continue_timeout): Returns the
+  #     continue timeout.
+  # *   [#continue_timeout=](rdoc-ref:Net::HTTP#continue_timeout=): Sets the
+  #     continue timeout seconds.
+  # *   [:keep_alive_timeout](rdoc-ref:Net::HTTP#keep_alive_timeout): Returns the
+  #     keep-alive timeout.
+  # *   [:keep_alive_timeout=](rdoc-ref:Net::HTTP#keep_alive_timeout=): Sets the
+  #     keep-alive timeout.
+  # *   [:max_retries](rdoc-ref:Net::HTTP#max_retries): Returns the maximum
+  #     retries.
+  # *   [#max_retries=](rdoc-ref:Net::HTTP#max_retries=): Sets the maximum
+  #     retries.
+  # *   [:open_timeout](rdoc-ref:Net::HTTP#open_timeout): Returns the open
+  #     timeout.
+  # *   [:open_timeout=](rdoc-ref:Net::HTTP#open_timeout=): Sets the open timeout.
+  # *   [:read_timeout](rdoc-ref:Net::HTTP#read_timeout): Returns the open
+  #     timeout.
+  # *   [:read_timeout=](rdoc-ref:Net::HTTP#read_timeout=): Sets the read timeout.
+  # *   [:ssl_timeout](rdoc-ref:Net::HTTP#ssl_timeout): Returns the ssl timeout.
+  # *   [:ssl_timeout=](rdoc-ref:Net::HTTP#ssl_timeout=): Sets the ssl timeout.
+  # *   [:write_timeout](rdoc-ref:Net::HTTP#write_timeout): Returns the write
+  #     timeout.
+  # *   [write_timeout=](rdoc-ref:Net::HTTP#write_timeout=): Sets the write
+  #     timeout.
+  #
+  #
+  # ### Requests
+  #
+  # *   [::get](rdoc-ref:Net::HTTP.get): Sends a GET request and returns the
+  #     string response body.
+  # *   [::get_print](rdoc-ref:Net::HTTP.get_print): Sends a GET request and write
+  #     the string response body to $stdout.
+  # *   [::get_response](rdoc-ref:Net::HTTP.get_response): Sends a GET request and
+  #     returns a response object.
+  # *   [::post_form](rdoc-ref:Net::HTTP.post_form): Sends a POST request with
+  #     form data and returns a response object.
+  # *   [::post](rdoc-ref:Net::HTTP.post): Sends a POST request with data and
+  #     returns a response object.
+  # *   [#copy](rdoc-ref:Net::HTTP#copy): Sends a COPY request and returns a
+  #     response object.
+  # *   [#delete](rdoc-ref:Net::HTTP#delete): Sends a DELETE request and returns a
+  #     response object.
+  # *   [#get](rdoc-ref:Net::HTTP#get): Sends a GET request and returns a response
+  #     object.
+  # *   [#head](rdoc-ref:Net::HTTP#head): Sends a HEAD request and returns a
+  #     response object.
+  # *   [#lock](rdoc-ref:Net::HTTP#lock): Sends a LOCK request and returns a
+  #     response object.
+  # *   [#mkcol](rdoc-ref:Net::HTTP#mkcol): Sends a MKCOL request and returns a
+  #     response object.
+  # *   [#move](rdoc-ref:Net::HTTP#move): Sends a MOVE request and returns a
+  #     response object.
+  # *   [#options](rdoc-ref:Net::HTTP#options): Sends a OPTIONS request and
+  #     returns a response object.
+  # *   [#patch](rdoc-ref:Net::HTTP#patch): Sends a PATCH request and returns a
+  #     response object.
+  # *   [#post](rdoc-ref:Net::HTTP#post): Sends a POST request and returns a
+  #     response object.
+  # *   [#propfind](rdoc-ref:Net::HTTP#propfind): Sends a PROPFIND request and
+  #     returns a response object.
+  # *   [#proppatch](rdoc-ref:Net::HTTP#proppatch): Sends a PROPPATCH request and
+  #     returns a response object.
+  # *   [#put](rdoc-ref:Net::HTTP#put): Sends a PUT request and returns a response
+  #     object.
+  # *   [#request](rdoc-ref:Net::HTTP#request): Sends a request and returns a
+  #     response object.
+  # *   [#request_get](rdoc-ref:Net::HTTP#request_get) (aliased as
+  #     [#get2](rdoc-ref:Net::HTTP#get2)): Sends a GET request and forms a
+  #     response object; if a block given, calls the block with the object,
+  #     otherwise returns the object.
+  # *   [#request_head](rdoc-ref:Net::HTTP#request_head) (aliased as
+  #     [#head2](rdoc-ref:Net::HTTP#head2)): Sends a HEAD request and forms a
+  #     response object; if a block given, calls the block with the object,
+  #     otherwise returns the object.
+  # *   [#request_post](rdoc-ref:Net::HTTP#request_post) (aliased as
+  #     [#post2](rdoc-ref:Net::HTTP#post2)): Sends a POST request and forms a
+  #     response object; if a block given, calls the block with the object,
+  #     otherwise returns the object.
+  # *   [#send_request](rdoc-ref:Net::HTTP#send_request): Sends a request and
+  #     returns a response object.
+  # *   [#trace](rdoc-ref:Net::HTTP#trace): Sends a TRACE request and returns a
+  #     response object.
+  # *   [#unlock](rdoc-ref:Net::HTTP#unlock): Sends an UNLOCK request and returns
+  #     a response object.
+  #
+  #
+  # ### Responses
+  #
+  # *   [:close_on_empty_response](rdoc-ref:Net::HTTP#close_on_empty_response):
+  #     Returns whether to close connection on empty response.
+  # *   [:close_on_empty_response=](rdoc-ref:Net::HTTP#close_on_empty_response=):
+  #     Sets whether to close connection on empty response.
+  # *   [:ignore_eof](rdoc-ref:Net::HTTP#ignore_eof): Returns whether to ignore
+  #     end-of-file when reading a response body with `Content-Length` headers.
+  # *   [:ignore_eof=](rdoc-ref:Net::HTTP#ignore_eof=): Sets whether to ignore
+  #     end-of-file when reading a response body with `Content-Length` headers.
+  # *   [:response_body_encoding](rdoc-ref:Net::HTTP#response_body_encoding):
+  #     Returns the encoding to use for the response body.
+  # *   [#response_body_encoding=](rdoc-ref:Net::HTTP#response_body_encoding=):
+  #     Sets the response body encoding.
+  #
+  #
+  # ### Proxies
+  #
+  # *   [:proxy_address](rdoc-ref:Net::HTTP#proxy_address): Returns the proxy
+  #     address.
+  # *   [:proxy_address=](rdoc-ref:Net::HTTP#proxy_address=): Sets the proxy
+  #     address.
+  # *   [::proxy_class?](rdoc-ref:Net::HTTP.proxy_class?): Returns whether `self`
+  #     is a proxy class.
+  # *   [#proxy?](rdoc-ref:Net::HTTP#proxy?): Returns whether `self` has a proxy.
+  # *   [#proxy_address](rdoc-ref:Net::HTTP#proxy_address) (aliased as
+  #     [#proxyaddr](rdoc-ref:Net::HTTP#proxyaddr)): Returns the proxy address.
+  # *   [#proxy_from_env?](rdoc-ref:Net::HTTP#proxy_from_env?): Returns whether
+  #     the proxy is taken from an environment variable.
+  # *   [:proxy_from_env=](rdoc-ref:Net::HTTP#proxy_from_env=): Sets whether the
+  #     proxy is to be taken from an environment variable.
+  # *   [:proxy_pass](rdoc-ref:Net::HTTP#proxy_pass): Returns the proxy password.
+  # *   [:proxy_pass=](rdoc-ref:Net::HTTP#proxy_pass=): Sets the proxy password.
+  # *   [:proxy_port](rdoc-ref:Net::HTTP#proxy_port): Returns the proxy port.
+  # *   [:proxy_port=](rdoc-ref:Net::HTTP#proxy_port=): Sets the proxy port.
+  # *   [#proxy_user](rdoc-ref:Net::HTTP#proxy_user): Returns the proxy user name.
+  # *   [:proxy_user=](rdoc-ref:Net::HTTP#proxy_user=): Sets the proxy user.
+  #
+  #
+  # ### Security
+  #
+  # *   [:ca_file](rdoc-ref:Net::HTTP#ca_file): Returns the path to a CA
+  #     certification file.
+  # *   [:ca_file=](rdoc-ref:Net::HTTP#ca_file=): Sets the path to a CA
+  #     certification file.
+  # *   [:ca_path](rdoc-ref:Net::HTTP#ca_path): Returns the path of to CA
+  #     directory containing certification files.
+  # *   [:ca_path=](rdoc-ref:Net::HTTP#ca_path=): Sets the path of to CA directory
+  #     containing certification files.
+  # *   [:cert](rdoc-ref:Net::HTTP#cert): Returns the OpenSSL::X509::Certificate
+  #     object to be used for client certification.
+  # *   [:cert=](rdoc-ref:Net::HTTP#cert=): Sets the OpenSSL::X509::Certificate
+  #     object to be used for client certification.
+  # *   [:cert_store](rdoc-ref:Net::HTTP#cert_store): Returns the X509::Store to
+  #     be used for verifying peer certificate.
+  # *   [:cert_store=](rdoc-ref:Net::HTTP#cert_store=): Sets the X509::Store to be
+  #     used for verifying peer certificate.
+  # *   [:ciphers](rdoc-ref:Net::HTTP#ciphers): Returns the available SSL ciphers.
+  # *   [:ciphers=](rdoc-ref:Net::HTTP#ciphers=): Sets the available SSL ciphers.
+  # *   [:extra_chain_cert](rdoc-ref:Net::HTTP#extra_chain_cert): Returns the
+  #     extra X509 certificates to be added to the certificate chain.
+  # *   [:extra_chain_cert=](rdoc-ref:Net::HTTP#extra_chain_cert=): Sets the extra
+  #     X509 certificates to be added to the certificate chain.
+  # *   [:key](rdoc-ref:Net::HTTP#key): Returns the OpenSSL::PKey::RSA or
+  #     OpenSSL::PKey::DSA object.
+  # *   [:key=](rdoc-ref:Net::HTTP#key=): Sets the OpenSSL::PKey::RSA or
+  #     OpenSSL::PKey::DSA object.
+  # *   [:max_version](rdoc-ref:Net::HTTP#max_version): Returns the maximum SSL
+  #     version.
+  # *   [:max_version=](rdoc-ref:Net::HTTP#max_version=): Sets the maximum SSL
+  #     version.
+  # *   [:min_version](rdoc-ref:Net::HTTP#min_version): Returns the minimum SSL
+  #     version.
+  # *   [:min_version=](rdoc-ref:Net::HTTP#min_version=): Sets the minimum SSL
+  #     version.
+  # *   [#peer_cert](rdoc-ref:Net::HTTP#peer_cert): Returns the X509 certificate
+  #     chain for the session's socket peer.
+  # *   [:ssl_version](rdoc-ref:Net::HTTP#ssl_version): Returns the SSL version.
+  # *   [:ssl_version=](rdoc-ref:Net::HTTP#ssl_version=): Sets the SSL version.
+  # *   [#use_ssl=](rdoc-ref:Net::HTTP#use_ssl=): Sets whether a new session is to
+  #     use Transport Layer Security.
+  # *   [#use_ssl?](rdoc-ref:Net::HTTP#use_ssl?): Returns whether `self` uses SSL.
+  # *   [:verify_callback](rdoc-ref:Net::HTTP#verify_callback): Returns the
+  #     callback for the server certification verification.
+  # *   [:verify_callback=](rdoc-ref:Net::HTTP#verify_callback=): Sets the
+  #     callback for the server certification verification.
+  # *   [:verify_depth](rdoc-ref:Net::HTTP#verify_depth): Returns the maximum
+  #     depth for the certificate chain verification.
+  # *   [:verify_depth=](rdoc-ref:Net::HTTP#verify_depth=): Sets the maximum depth
+  #     for the certificate chain verification.
+  # *   [:verify_hostname](rdoc-ref:Net::HTTP#verify_hostname): Returns the flags
+  #     for server the certification verification at the beginning of the SSL/TLS
+  #     session.
+  # *   [:verify_hostname=](rdoc-ref:Net::HTTP#verify_hostname=): Sets he flags
+  #     for server the certification verification at the beginning of the SSL/TLS
+  #     session.
+  # *   [:verify_mode](rdoc-ref:Net::HTTP#verify_mode): Returns the flags for
+  #     server the certification verification at the beginning of the SSL/TLS
+  #     session.
+  # *   [:verify_mode=](rdoc-ref:Net::HTTP#verify_mode=): Sets the flags for
+  #     server the certification verification at the beginning of the SSL/TLS
+  #     session.
+  #
+  #
+  # ### Addresses and Ports
+  #
+  # *   [:address](rdoc-ref:Net::HTTP#address): Returns the string host name or
+  #     host IP.
+  # *   [::default_port](rdoc-ref:Net::HTTP.default_port): Returns integer 80, the
+  #     default port to use for HTTP requests.
+  # *   [::http_default_port](rdoc-ref:Net::HTTP.http_default_port): Returns
+  #     integer 80, the default port to use for HTTP requests.
+  # *   [::https_default_port](rdoc-ref:Net::HTTP.https_default_port): Returns
+  #     integer 443, the default port to use for HTTPS requests.
+  # *   [#ipaddr](rdoc-ref:Net::HTTP#ipaddr): Returns the IP address for the
+  #     connection.
+  # *   [#ipaddr=](rdoc-ref:Net::HTTP#ipaddr=): Sets the IP address for the
+  #     connection.
+  # *   [:local_host](rdoc-ref:Net::HTTP#local_host): Returns the string local
+  #     host used to establish the connection.
+  # *   [:local_host=](rdoc-ref:Net::HTTP#local_host=): Sets the string local host
+  #     used to establish the connection.
+  # *   [:local_port](rdoc-ref:Net::HTTP#local_port): Returns the integer local
+  #     port used to establish the connection.
+  # *   [:local_port=](rdoc-ref:Net::HTTP#local_port=): Sets the integer local
+  #     port used to establish the connection.
+  # *   [:port](rdoc-ref:Net::HTTP#port): Returns the integer port number.
+  #
+  #
+  # ### HTTP Version
+  #
+  # *   [::version_1_2?](rdoc-ref:Net::HTTP.version_1_2?) (aliased as
+  #     [::is_version_1_2?](rdoc-ref:Net::HTTP.is_version_1_2?) and
+  #     [::version_1_2](rdoc-ref:Net::HTTP.version_1_2)): Returns true; retained
+  #     for compatibility.
+  #
+  #
+  # ### Debugging
+  #
+  # *   [#set_debug_output](rdoc-ref:Net::HTTP#set_debug_output): Sets the output
+  #     stream for debugging.
   #
   class HTTP < Protocol
     # :stopdoc:
@@ -549,7 +885,7 @@ module Net
     #   rdoc-file=lib/net/http.rb
     #   - default_port()
     # -->
-    # Returns intger `80`, the default port to use for HTTP requests:
+    # Returns integer `80`, the default port to use for HTTP requests:
     #
     #     Net::HTTP.default_port # => 80
     #
@@ -582,15 +918,12 @@ module Net
     # -->
     # Creates a new Net::HTTP object, `http`, via Net::HTTP.new:
     #
-    #     Net::HTTP.new(address, port, p_addr, p_port, p_user, p_pass)
-    #
-    # *   For arguments `hostname` through `p_pass`, see Net::HTTP.new.
+    # *   For arguments `address` and `port`, see Net::HTTP.new.
+    # *   For proxy-defining arguments `p_addr` through `p_pass`, see [Proxy
+    #     Server](rdoc-ref:Net::HTTP@Proxy+Server).
     # *   For argument `opts`, see below.
     #
     #
-    # Note: If `port` is `nil` and `opts[:use_ssl]` is a truthy value, the value
-    # passed to `new` is Net::HTTP.https_default_port, not `port`.
-    #
     # With no block given:
     #
     # *   Calls `http.start` with no block (see #start), which opens a TCP
@@ -664,6 +997,10 @@ module Net
     # *   #verify_mode
     # *   #write_timeout
     #
+    #
+    # Note: If `port` is `nil` and `opts[:use_ssl]` is a truthy value, the value
+    # passed to `new` is Net::HTTP.https_default_port, not `port`.
+    #
     def self.start: (String address, ?Integer? port, ?String | :ENV | nil p_addr, ?Integer? p_port, ?String? p_user, ?String? p_pass, ?Hash[Symbol, untyped]? opt) -> Net::HTTP
                   | [T] (String address, ?Integer? port, ?String | :ENV | nil p_addr, ?Integer? p_port, ?String? p_user, ?String? p_pass, ?Hash[Symbol, untyped]? opt) { (Net::HTTP) -> T } -> T
 
@@ -676,11 +1013,36 @@ module Net
 
     # <!--
     #   rdoc-file=lib/net/http.rb
-    #   - new(address, port = nil)
+    #   - new(address, port = nil, p_addr = :ENV, p_port = nil, p_user = nil, p_pass = nil, p_no_proxy = nil)
     # -->
-    # Creates a new Net::HTTP object for the specified server address, without
-    # opening the TCP connection or initializing the HTTP session. The `address`
-    # should be a DNS hostname or IP address.
+    # Returns a new Net::HTTP object `http` (but does not open a TCP connection or
+    # HTTP session).
+    #
+    # With only string argument `address` given (and `ENV['http_proxy']` undefined
+    # or `nil`), the returned `http`:
+    #
+    # *   Has the given address.
+    # *   Has the default port number, Net::HTTP.default_port (80).
+    # *   Has no proxy.
+    #
+    #
+    # Example:
+    #
+    #     http = Net::HTTP.new(hostname)
+    #     # => #<Net::HTTP jsonplaceholder.typicode.com:80 open=false>
+    #     http.address # => "jsonplaceholder.typicode.com"
+    #     http.port    # => 80
+    #     http.proxy?  # => false
+    #
+    # With integer argument `port` also given, the returned `http` has the given
+    # port:
+    #
+    #     http = Net::HTTP.new(hostname, 8000)
+    #     # => #<Net::HTTP jsonplaceholder.typicode.com:8000 open=false>
+    #     http.port # => 8000
+    #
+    # For proxy-defining arguments `p_addr` through `p_no_proxy`, see [Proxy
+    # Server](rdoc-ref:Net::HTTP@Proxy+Server).
     #
     def self.new: (String address, ?Integer? port, ?String | :ENV | nil p_addr, ?Integer? p_port, ?String? p_user, ?String? p_pass, ?untyped? p_no_proxy) -> Net::HTTP
 
@@ -751,40 +1113,52 @@ module Net
     def set_debug_output: (IO output) -> void
 
     # <!-- rdoc-file=lib/net/http.rb -->
-    # The DNS host name or IP address to connect to.
+    # Returns the string host name or host IP given as argument `address` in ::new.
     #
     attr_reader address: String
 
     # <!-- rdoc-file=lib/net/http.rb -->
-    # The port number to connect to.
+    # Returns the integer port number given as argument `port` in ::new.
     #
     attr_reader port: Integer
 
     # <!-- rdoc-file=lib/net/http.rb -->
-    # The local host used to establish the connection.
+    # Sets or returns the string local host used to establish the connection;
+    # initially `nil`.
     #
     attr_accessor local_host: String
 
     # <!-- rdoc-file=lib/net/http.rb -->
-    # The local port used to establish the connection.
+    # Sets or returns the integer local port used to establish the connection;
+    # initially `nil`.
     #
     attr_accessor local_port: Integer
 
+    # <!-- rdoc-file=lib/net/http.rb -->
+    # Sets whether to determine the proxy from environment variable
+    # '`ENV['http_proxy']`'; see [Proxy Using
+    # ENV['http_proxy']](rdoc-ref:Net::HTTP@Proxy+Using+-27ENV-5B-27http_proxy-27-5D
+    # -27).
+    #
     attr_writer proxy_from_env: untyped
 
     # <!-- rdoc-file=lib/net/http.rb -->
+    # Sets the proxy address; see [Proxy Server](rdoc-ref:Net::HTTP@Proxy+Server).
     #
     attr_accessor proxy_address: String?
 
     # <!-- rdoc-file=lib/net/http.rb -->
+    # Sets the proxy port; see [Proxy Server](rdoc-ref:Net::HTTP@Proxy+Server).
     #
     attr_accessor proxy_port: Integer?
 
     # <!-- rdoc-file=lib/net/http.rb -->
+    # Sets the proxy user; see [Proxy Server](rdoc-ref:Net::HTTP@Proxy+Server).
     #
     attr_accessor proxy_user: String?
 
     # <!-- rdoc-file=lib/net/http.rb -->
+    # Sets the proxy password; see [Proxy Server](rdoc-ref:Net::HTTP@Proxy+Server).
     #
     attr_accessor proxy_pass: String?
 
@@ -825,18 +1199,15 @@ module Net
     attr_accessor ipaddr: String?
 
     # <!-- rdoc-file=lib/net/http.rb -->
-    # Number of seconds to wait for the connection to open. Any number may be used,
-    # including Floats for fractional seconds. If the HTTP object cannot open a
-    # connection in this many seconds, it raises a Net::OpenTimeout exception. The
-    # default value is 60 seconds.
+    # Sets or returns the numeric (Integer or Float) number of seconds to wait for a
+    # connection to open; initially 60. If the connection is not made in the given
+    # interval, an exception is raised.
     #
     attr_accessor open_timeout: Float | Integer
 
     # <!-- rdoc-file=lib/net/http.rb -->
-    # Number of seconds to wait for one block to be read (via one read(2) call). Any
-    # number may be used, including Floats for fractional seconds. If the HTTP
-    # object cannot read data in this many seconds, it raises a Net::ReadTimeout
-    # exception. The default value is 60 seconds.
+    # Returns the numeric (Integer or Float) number of seconds to wait for one block
+    # to be read (via one read(2) call); see #read_timeout=.
     # ----
     # <!--
     #   rdoc-file=lib/net/http.rb
@@ -856,11 +1227,8 @@ module Net
     attr_accessor read_timeout: Float | Integer
 
     # <!-- rdoc-file=lib/net/http.rb -->
-    # Number of seconds to wait for one block to be written (via one write(2) call).
-    # Any number may be used, including Floats for fractional seconds. If the HTTP
-    # object cannot write data in this many seconds, it raises a Net::WriteTimeout
-    # exception. The default value is 60 seconds. Net::WriteTimeout is not raised on
-    # Windows.
+    # Returns the numeric (Integer or Float) number of seconds to wait for one block
+    # to be written (via one write(2) call); see #write_timeout=.
     # ----
     # <!--
     #   rdoc-file=lib/net/http.rb
@@ -869,10 +1237,28 @@ module Net
     # Sets the write timeout, in seconds, for `self` to integer `sec`; the initial
     # value is 60.
     #
-    # Argument `sec` must be a non-negative numeric value.
+    # Argument `sec` must be a non-negative numeric value:
+    #
+    #     _uri = uri.dup
+    #     _uri.path = '/posts'
+    #     body = 'bar' * 200000
+    #     data = <<EOF
+    #     {"title": "foo", "body": "#{body}", "userId": "1"}
+    #     EOF
+    #     headers = {'content-type': 'application/json'}
+    #     http = Net::HTTP.new(hostname)
+    #     http.write_timeout # => 60
+    #     http.post(_uri.path, data, headers)
+    #     # => #<Net::HTTPCreated 201 Created readbody=true>
+    #     http.write_timeout = 0
+    #     http.post(_uri.path, data, headers) # Raises Net::WriteTimeout.
     #
     attr_accessor write_timeout: Float | Integer
 
+    # <!-- rdoc-file=lib/net/http.rb -->
+    # Returns the maximum number of times to retry an idempotent request; see
+    # #max_retries=.
+    # ----
     # <!--
     #   rdoc-file=lib/net/http.rb
     #   - max_retries=(retries)
@@ -890,22 +1276,23 @@ module Net
     attr_accessor max_retries: Integer
 
     # <!-- rdoc-file=lib/net/http.rb -->
-    # Seconds to wait for 100 Continue response. If the HTTP object does not receive
-    # a response in this many seconds it sends the request body. The default value
-    # is `nil`.
+    # Returns the continue timeout value; see continue_timeout=.
     # ----
     # <!--
     #   rdoc-file=lib/net/http.rb
     #   - continue_timeout=(sec)
     # -->
-    # Setter for the continue_timeout attribute.
+    # Sets the continue timeout value, which is the number of seconds to wait for an
+    # expected 100 Continue response. If the HTTP object does not receive a response
+    # in this many seconds it sends the request body.
     #
     attr_accessor continue_timeout: Float | Integer | nil
 
     # <!-- rdoc-file=lib/net/http.rb -->
-    # Seconds to reuse the connection of the previous request. If the idle time is
-    # less than this Keep-Alive Timeout, Net::HTTP reuses the TCP/IP socket used by
-    # the previous communication. The default value is 2 seconds.
+    # Sets or returns the numeric (Integer or Float) number of seconds to keep the
+    # connection open after a request is sent; initially 2. If a new request is made
+    # during the given interval, the still-open connection is used; otherwise the
+    # connection will have been closed and a new connection is opened.
     #
     attr_accessor keep_alive_timeout: Float | Integer
 
@@ -913,7 +1300,19 @@ module Net
     #   rdoc-file=lib/net/http.rb
     #   - started?()
     # -->
-    # Returns true if the HTTP session has been started.
+    # Returns `true` if the HTTP session has been started:
+    #
+    #     http = Net::HTTP.new(hostname)
+    #     http.started? # => false
+    #     http.start
+    #     http.started? # => true
+    #     http.finish # => nil
+    #     http.started? # => false
+    #
+    #     Net::HTTP.start(hostname) do |http|
+    #       http.started?
+    #     end # => true
+    #     http.started? # => false
     #
     def started?: () -> bool
 
@@ -924,13 +1323,17 @@ module Net
     #
     alias active? started?
 
+    # <!-- rdoc-file=lib/net/http.rb -->
+    # Sets or returns whether to close the connection when the response is empty;
+    # initially `false`.
+    #
     attr_accessor close_on_empty_response: untyped
 
     # <!--
     #   rdoc-file=lib/net/http.rb
     #   - use_ssl?()
     # -->
-    # Returns true if SSL/TLS is being used with HTTP.
+    # Returns `true` if `self` uses SSL, `false` otherwise. See Net::HTTP#use_ssl=.
     #
     def use_ssl?: () -> bool
 
@@ -938,8 +1341,12 @@ module Net
     #   rdoc-file=lib/net/http.rb
     #   - use_ssl=(flag)
     # -->
-    # Turn on/off SSL. This flag must be set before starting session. If you change
-    # use_ssl value after session started, a Net::HTTP object raises IOError.
+    # Sets whether a new session is to use [Transport Layer
+    # Security](https://en.wikipedia.org/wiki/Transport_Layer_Security):
+    #
+    # Raises IOError if attempting to change during a session.
+    #
+    # Raises OpenSSL::SSL::SSLError if the port is not an HTTPS port.
     #
     def use_ssl=: (boolish flag) -> void
 
@@ -948,87 +1355,95 @@ module Net
     SSL_ATTRIBUTES: Array[Symbol]
 
     # <!-- rdoc-file=lib/net/http.rb -->
-    # Sets path of a CA certification file in PEM format.
-    #
-    # The file can contain several CA certificates.
+    # Sets or returns the path to a CA certification file in PEM format.
     #
     attr_accessor ca_file: untyped
 
     # <!-- rdoc-file=lib/net/http.rb -->
-    # Sets path of a CA certification directory containing certifications in PEM
-    # format.
+    # Sets or returns the path of to CA directory containing certification files in
+    # PEM format.
     #
     attr_accessor ca_path: untyped
 
     # <!-- rdoc-file=lib/net/http.rb -->
-    # Sets an OpenSSL::X509::Certificate object as client certificate. (This method
-    # is appeared in Michal Rokos's OpenSSL extension).
+    # Sets or returns the OpenSSL::X509::Certificate object to be used for client
+    # certification.
     #
     attr_accessor cert: untyped
 
     # <!-- rdoc-file=lib/net/http.rb -->
-    # Sets the X509::Store to verify peer certificate.
+    # Sets or returns the X509::Store to be used for verifying peer certificate.
     #
     attr_accessor cert_store: untyped
 
     # <!-- rdoc-file=lib/net/http.rb -->
-    # Sets the available ciphers.  See OpenSSL::SSL::SSLContext#ciphers=
+    # Sets or returns the available SSL ciphers. See
+    # [OpenSSL::SSL::SSLContext#ciphers=](rdoc-ref:OpenSSL::SSL::SSLContext#ciphers-
+    # 3D).
     #
     attr_accessor ciphers: untyped
 
     # <!-- rdoc-file=lib/net/http.rb -->
-    # Sets the extra X509 certificates to be added to the certificate chain. See
-    # OpenSSL::SSL::SSLContext#extra_chain_cert=
+    # Sets or returns the extra X509 certificates to be added to the certificate
+    # chain. See
+    # [OpenSSL::SSL::SSLContext#add_certificate](rdoc-ref:OpenSSL::SSL::SSLContext#a
+    # dd_certificate).
     #
     attr_accessor extra_chain_cert: untyped
 
     # <!-- rdoc-file=lib/net/http.rb -->
-    # Sets an OpenSSL::PKey::RSA or OpenSSL::PKey::DSA object. (This method is
-    # appeared in Michal Rokos's OpenSSL extension.)
+    # Sets or returns the OpenSSL::PKey::RSA or OpenSSL::PKey::DSA object.
     #
     attr_accessor key: untyped
 
     # <!-- rdoc-file=lib/net/http.rb -->
-    # Sets the SSL timeout seconds.
+    # Sets or returns the SSL timeout seconds.
     #
     attr_accessor ssl_timeout: untyped
 
     # <!-- rdoc-file=lib/net/http.rb -->
-    # Sets the SSL version.  See OpenSSL::SSL::SSLContext#ssl_version=
+    # Sets or returns the SSL version. See
+    # [OpenSSL::SSL::SSLContext#ssl_version=](rdoc-ref:OpenSSL::SSL::SSLContext#ssl_
+    # version-3D).
     #
     attr_accessor ssl_version: untyped
 
     # <!-- rdoc-file=lib/net/http.rb -->
-    # Sets the minimum SSL version.  See OpenSSL::SSL::SSLContext#min_version=
+    # Sets or returns the minimum SSL version. See
+    # [OpenSSL::SSL::SSLContext#min_version=](rdoc-ref:OpenSSL::SSL::SSLContext#min_
+    # version-3D).
     #
     attr_accessor min_version: untyped
 
     # <!-- rdoc-file=lib/net/http.rb -->
-    # Sets the maximum SSL version.  See OpenSSL::SSL::SSLContext#max_version=
+    # Sets or returns the maximum SSL version. See
+    # [OpenSSL::SSL::SSLContext#max_version=](rdoc-ref:OpenSSL::SSL::SSLContext#max_
+    # version-3D).
     #
     attr_accessor max_version: untyped
 
     # <!-- rdoc-file=lib/net/http.rb -->
-    # Sets the verify callback for the server certification verification.
+    # Sets or returns the callback for the server certification verification.
     #
     attr_accessor verify_callback: untyped
 
     # <!-- rdoc-file=lib/net/http.rb -->
-    # Sets the maximum depth for the certificate chain verification.
+    # Sets or returns the maximum depth for the certificate chain verification.
     #
     attr_accessor verify_depth: untyped
 
     # <!-- rdoc-file=lib/net/http.rb -->
-    # Sets the flags for server the certification verification at beginning of
-    # SSL/TLS session.
-    #
-    # OpenSSL::SSL::VERIFY_NONE or OpenSSL::SSL::VERIFY_PEER are acceptable.
+    # Sets or returns the flags for server the certification verification at the
+    # beginning of the SSL/TLS session. OpenSSL::SSL::VERIFY_NONE or
+    # OpenSSL::SSL::VERIFY_PEER are acceptable.
     #
     attr_accessor verify_mode: untyped
 
     # <!-- rdoc-file=lib/net/http.rb -->
-    # Sets to check the server certificate is valid for the hostname. See
-    # OpenSSL::SSL::SSLContext#verify_hostname=
+    # Sets or returns whether to verify that the server certificate is valid for the
+    # hostname. See
+    # [OpenSSL::SSL::SSLContext#verify_hostname=](rdoc-ref:OpenSSL::SSL::SSLContext#
+    # attribute-i-verify_mode).
     #
     attr_accessor verify_hostname: untyped
 
@@ -1036,7 +1451,8 @@ module Net
     #   rdoc-file=lib/net/http.rb
     #   - peer_cert()
     # -->
-    # Returns the X.509 certificates the server presented.
+    # Returns the X509 certificate chain (an array of strings) for the session's
+    # socket peer, or `nil` if none.
     #
     def peer_cert: () -> (nil | untyped)
 
@@ -1044,14 +1460,25 @@ module Net
     #   rdoc-file=lib/net/http.rb
     #   - start() { |http| ... }
     # -->
-    # Opens a TCP connection and HTTP session.
+    # Starts an HTTP session.
+    #
+    # Without a block, returns `self`:
     #
-    # When this method is called with a block, it passes the Net::HTTP object to the
-    # block, and closes the TCP connection and HTTP session after the block has been
-    # executed.
+    #     http = Net::HTTP.new(hostname)
+    #     # => #<Net::HTTP jsonplaceholder.typicode.com:80 open=false>
+    #     http.start
+    #     # => #<Net::HTTP jsonplaceholder.typicode.com:80 open=true>
+    #     http.started? # => true
+    #     http.finish
+    #
+    # With a block, calls the block with `self`, finishes the session when the block
+    # exits, and returns the block's value:
     #
-    # When called with a block, it returns the return value of the block; otherwise,
-    # it returns self.
+    #     http.start do |http|
+    #       http
+    #     end
+    #     # => #<Net::HTTP jsonplaceholder.typicode.com:80 open=false>
+    #     http.started? # => false
     #
     def start: [T] () { (Net::HTTP) -> T } -> T
              | () -> Net::HTTP
@@ -1062,8 +1489,15 @@ module Net
     #   rdoc-file=lib/net/http.rb
     #   - finish()
     # -->
-    # Finishes the HTTP session and closes the TCP connection. Raises IOError if the
-    # session has not been started.
+    # Finishes the HTTP session:
+    #
+    #     http = Net::HTTP.new(hostname)
+    #     http.start
+    #     http.started? # => true
+    #     http.finish   # => nil
+    #     http.started? # => false
+    #
+    # Raises IOError if not in a session.
     #
     def finish: () -> void
 
@@ -1085,27 +1519,31 @@ module Net
     #   rdoc-file=lib/net/http.rb
     #   - proxy_class?()
     # -->
-    # returns true if self is a class which was created by HTTP::Proxy.
+    # Returns true if self is a class which was created by HTTP::Proxy.
     #
     def self.proxy_class?: () -> bool
 
     # <!-- rdoc-file=lib/net/http.rb -->
-    # Address of proxy host. If Net::HTTP does not use a proxy, nil.
+    # Returns the address of the proxy host, or `nil` if none; see
+    # Net::HTTP@Proxy+Server.
     #
     attr_reader self.proxy_address: String?
 
     # <!-- rdoc-file=lib/net/http.rb -->
-    # Port number of proxy host. If Net::HTTP does not use a proxy, nil.
+    # Returns the port number of the proxy host, or `nil` if none; see
+    # Net::HTTP@Proxy+Server.
     #
     attr_reader self.proxy_port: Integer?
 
     # <!-- rdoc-file=lib/net/http.rb -->
-    # User name for accessing proxy. If Net::HTTP does not use a proxy, nil.
+    # Returns the user name for accessing the proxy, or `nil` if none; see
+    # Net::HTTP@Proxy+Server.
     #
     attr_reader self.proxy_user: String?
 
     # <!-- rdoc-file=lib/net/http.rb -->
-    # User password for accessing proxy. If Net::HTTP does not use a proxy, nil.
+    # Returns the password for accessing the proxy, or `nil` if none; see
+    # Net::HTTP@Proxy+Server.
     #
     attr_reader self.proxy_pass: String?
 
@@ -1113,7 +1551,8 @@ module Net
     #   rdoc-file=lib/net/http.rb
     #   - proxy?()
     # -->
-    # True if requests for this connection will be proxied
+    # Returns `true` if a proxy server is defined, `false` otherwise; see [Proxy
+    # Server](rdoc-ref:Net::HTTP@Proxy+Server).
     #
     def proxy?: () -> bool
 
@@ -1121,7 +1560,8 @@ module Net
     #   rdoc-file=lib/net/http.rb
     #   - proxy_from_env?()
     # -->
-    # True if the proxy for this connection is determined from the environment
+    # Returns `true` if the proxy server is defined in the environment, `false`
+    # otherwise; see [Proxy Server](rdoc-ref:Net::HTTP@Proxy+Server).
     #
     def proxy_from_env?: () -> bool
 
@@ -1145,39 +1585,33 @@ module Net
 
     # <!--
     #   rdoc-file=lib/net/http.rb
-    #   - get(path, initheader = nil, dest = nil) { |body_segment| ... }
+    #   - get(path, initheader = nil) {|res| ... }
     # -->
-    # Retrieves data from `path` on the connected-to host which may be an absolute
-    # path String or a URI to extract the path from.
+    # Sends a GET request to the server; returns an instance of a subclass of
+    # Net::HTTPResponse.
     #
-    # `initheader` must be a Hash like { 'Accept' => '**/**', ... }, and it defaults
-    # to an empty hash. If `initheader` doesn't have the key 'accept-encoding', then
-    # a value of "gzip;q=1.0,deflate;q=0.6,identity;q=0.3" is used, so that gzip
-    # compression is used in preference to deflate compression, which is used in
-    # preference to no compression. Ruby doesn't have libraries to support the
-    # compress (Lempel-Ziv) compression, so that is not supported.  The intent of
-    # this is to reduce bandwidth by default.   If this routine sets up compression,
-    # then it does the decompression also, removing the header as well to prevent
-    # confusion.  Otherwise it leaves the body as it found it.
+    # The request is based on the Net::HTTP::Get object created from string `path`
+    # and initial headers hash `initheader`.
     #
-    # This method returns a Net::HTTPResponse object.
+    # With a block given, calls the block with the response body:
     #
-    # If called with a block, yields each fragment of the entity body in turn as a
-    # string as it is read from the socket.  Note that in this case, the returned
-    # response object will **not** contain a (meaningful) body.
+    #     http = Net::HTTP.new(hostname)
+    #     http.get('/todos/1') do |res|
+    #       p res
+    #     end # => #<Net::HTTPOK 200 OK readbody=true>
     #
-    # `dest` argument is obsolete. It still works but you must not use it.
+    # Output:
     #
-    # This method never raises an exception.
+    #     "{\n  \"userId\": 1,\n  \"id\": 1,\n  \"title\": \"delectus aut autem\",\n  \"completed\": false\n}"
     #
-    #     response = http.get('/index.html')
+    # With no block given, simply returns the response object:
     #
-    #     # using block
-    #     File.open('result.txt', 'w') {|f|
-    #       http.get('/~foo/') do |str|
-    #         f.write str
-    #       end
-    #     }
+    #     http.get('/') # => #<Net::HTTPOK 200 OK readbody=true>
+    #
+    # Related:
+    #
+    # *   Net::HTTP::Get: request class for HTTP method GET.
+    # *   Net::HTTP.get: sends GET request, returns response body.
     #
     def get: (String path, ?Hash[String, untyped] initheader, ?bot dest) ?{ (String body_segment) -> void } -> Net::HTTPResponse
 
@@ -1185,69 +1619,112 @@ module Net
     #   rdoc-file=lib/net/http.rb
     #   - head(path, initheader = nil)
     # -->
-    # Gets only the header from `path` on the connected-to host. `header` is a Hash
-    # like { 'Accept' => '**/**', ... }.
+    # Sends a HEAD request to the server; returns an instance of a subclass of
+    # Net::HTTPResponse.
     #
-    # This method returns a Net::HTTPResponse object.
+    # The request is based on the Net::HTTP::Head object created from string `path`
+    # and initial headers hash `initheader`:
     #
-    # This method never raises an exception.
-    #
-    #     response = nil
-    #     Net::HTTP.start('some.www.server', 80) {|http|
-    #       response = http.head('/index.html')
-    #     }
-    #     p response['content-type']
+    #     res = http.head('/todos/1') # => #<Net::HTTPOK 200 OK readbody=true>
+    #     res.body                    # => nil
+    #     res.to_hash.take(3)
+    #     # =>
+    #     [["date", ["Wed, 15 Feb 2023 15:25:42 GMT"]],
+    #      ["content-type", ["application/json; charset=utf-8"]],
+    #      ["connection", ["close"]]]
     #
     def head: (String path, ?Hash[String, untyped] initheader) -> Net::HTTPResponse
 
     # <!--
     #   rdoc-file=lib/net/http.rb
-    #   - post(path, data, initheader = nil, dest = nil) { |body_segment| ... }
+    #   - post(path, data, initheader = nil) {|res| ... }
     # -->
-    # Posts `data` (must be a String) to `path`. `header` must be a Hash like {
-    # 'Accept' => '**/**', ... }.
+    # Sends a POST request to the server; returns an instance of a subclass of
+    # Net::HTTPResponse.
     #
-    # This method returns a Net::HTTPResponse object.
+    # The request is based on the Net::HTTP::Post object created from string `path`,
+    # string `data`, and initial headers hash `initheader`.
     #
-    # If called with a block, yields each fragment of the entity body in turn as a
-    # string as it is read from the socket.  Note that in this case, the returned
-    # response object will **not** contain a (meaningful) body.
+    # With a block given, calls the block with the response body:
     #
-    # `dest` argument is obsolete. It still works but you must not use it.
+    #     data = '{"userId": 1, "id": 1, "title": "delectus aut autem", "completed": false}'
+    #     http = Net::HTTP.new(hostname)
+    #     http.post('/todos', data) do |res|
+    #       p res
+    #     end # => #<Net::HTTPCreated 201 Created readbody=true>
     #
-    # This method never raises exception.
+    # Output:
     #
-    #     response = http.post('/cgi-bin/search.rb', 'query=foo')
+    #     "{\n  \"{\\\"userId\\\": 1, \\\"id\\\": 1, \\\"title\\\": \\\"delectus aut autem\\\", \\\"completed\\\": false}\": \"\",\n  \"id\": 201\n}"
     #
-    #     # using block
-    #     File.open('result.txt', 'w') {|f|
-    #       http.post('/cgi-bin/search.rb', 'query=foo') do |str|
-    #         f.write str
-    #       end
-    #     }
+    # With no block given, simply returns the response object:
     #
-    # You should set Content-Type: header field for POST. If no Content-Type: field
-    # given, this method uses "application/x-www-form-urlencoded" by default.
+    #     http.post('/todos', data) # => #<Net::HTTPCreated 201 Created readbody=true>
+    #
+    # Related:
+    #
+    # *   Net::HTTP::Post: request class for HTTP method POST.
+    # *   Net::HTTP.post: sends POST request, returns response body.
     #
     def post: (String path, String data, ?Hash[String, untyped] initheader, ?bot dest) ?{ (String body_segment) -> void } -> Net::HTTPResponse
 
     # <!--
     #   rdoc-file=lib/net/http.rb
-    #   - patch(path, data, initheader = nil, dest = nil) { |body_segment| ... }
+    #   - patch(path, data, initheader = nil) {|res| ... }
     # -->
-    # Sends a PATCH request to the `path` and gets a response, as an HTTPResponse
-    # object.
+    # Sends a PATCH request to the server; returns an instance of a subclass of
+    # Net::HTTPResponse.
+    #
+    # The request is based on the Net::HTTP::Patch object created from string
+    # `path`, string `data`, and initial headers hash `initheader`.
+    #
+    # With a block given, calls the block with the response body:
+    #
+    #     data = '{"userId": 1, "id": 1, "title": "delectus aut autem", "completed": false}'
+    #     http = Net::HTTP.new(hostname)
+    #     http.patch('/todos/1', data) do |res|
+    #       p res
+    #     end # => #<Net::HTTPOK 200 OK readbody=true>
+    #
+    # Output:
+    #
+    #     "{\n  \"userId\": 1,\n  \"id\": 1,\n  \"title\": \"delectus aut autem\",\n  \"completed\": false,\n  \"{\\\"userId\\\": 1, \\\"id\\\": 1, \\\"title\\\": \\\"delectus aut autem\\\", \\\"completed\\\": false}\": \"\"\n}"
+    #
+    # With no block given, simply returns the response object:
+    #
+    #     http.patch('/todos/1', data) # => #<Net::HTTPCreated 201 Created readbody=true>
     #
     def patch: (String path, String data, ?Hash[String, untyped] initheader, ?bot dest) ?{ (String body_segment) -> void } -> Net::HTTPResponse
 
+    # <!--
+    #   rdoc-file=lib/net/http.rb
+    #   - put(path, data, initheader = nil)
+    # -->
+    # Sends a PUT request to the server; returns an instance of a subclass of
+    # Net::HTTPResponse.
+    #
+    # The request is based on the Net::HTTP::Put object created from string `path`,
+    # string `data`, and initial headers hash `initheader`.
+    #
+    #     data = '{"userId": 1, "id": 1, "title": "delectus aut autem", "completed": false}'
+    #     http = Net::HTTP.new(hostname)
+    #     http.put('/todos/1', data) # => #<Net::HTTPOK 200 OK readbody=true>
+    #
     def put: (String path, String data, ?Hash[String, untyped] initheader) -> Net::HTTPResponse
 
     # <!--
     #   rdoc-file=lib/net/http.rb
     #   - proppatch(path, body, initheader = nil)
     # -->
-    # Sends a PROPPATCH request to the `path` and gets a response, as an
-    # HTTPResponse object.
+    # Sends a PROPPATCH request to the server; returns an instance of a subclass of
+    # Net::HTTPResponse.
+    #
+    # The request is based on the Net::HTTP::Proppatch object created from string
+    # `path`, string `body`, and initial headers hash `initheader`.
+    #
+    #     data = '{"userId": 1, "id": 1, "title": "delectus aut autem", "completed": false}'
+    #     http = Net::HTTP.new(hostname)
+    #     http.proppatch('/todos/1', data)
     #
     def proppatch: (String path, String body, ?Hash[String, untyped] initheader) -> Net::HTTPResponse
 
@@ -1255,8 +1732,15 @@ module Net
     #   rdoc-file=lib/net/http.rb
     #   - lock(path, body, initheader = nil)
     # -->
-    # Sends a LOCK request to the `path` and gets a response, as an HTTPResponse
-    # object.
+    # Sends a LOCK request to the server; returns an instance of a subclass of
+    # Net::HTTPResponse.
+    #
+    # The request is based on the Net::HTTP::Lock object created from string `path`,
+    # string `body`, and initial headers hash `initheader`.
+    #
+    #     data = '{"userId": 1, "id": 1, "title": "delectus aut autem", "completed": false}'
+    #     http = Net::HTTP.new(hostname)
+    #     http.lock('/todos/1', data)
     #
     def lock: (String path, String body, ?Hash[String, untyped] initheader) -> Net::HTTPResponse
 
@@ -1264,8 +1748,15 @@ module Net
     #   rdoc-file=lib/net/http.rb
     #   - unlock(path, body, initheader = nil)
     # -->
-    # Sends a UNLOCK request to the `path` and gets a response, as an HTTPResponse
-    # object.
+    # Sends an UNLOCK request to the server; returns an instance of a subclass of
+    # Net::HTTPResponse.
+    #
+    # The request is based on the Net::HTTP::Unlock object created from string
+    # `path`, string `body`, and initial headers hash `initheader`.
+    #
+    #     data = '{"userId": 1, "id": 1, "title": "delectus aut autem", "completed": false}'
+    #     http = Net::HTTP.new(hostname)
+    #     http.unlock('/todos/1', data)
     #
     def unlock: (String path, String body, ?Hash[String, untyped] initheader) -> Net::HTTPResponse
 
@@ -1273,8 +1764,14 @@ module Net
     #   rdoc-file=lib/net/http.rb
     #   - options(path, initheader = nil)
     # -->
-    # Sends a OPTIONS request to the `path` and gets a response, as an HTTPResponse
-    # object.
+    # Sends an Options request to the server; returns an instance of a subclass of
+    # Net::HTTPResponse.
+    #
+    # The request is based on the Net::HTTP::Options object created from string
+    # `path` and initial headers hash `initheader`.
+    #
+    #     http = Net::HTTP.new(hostname)
+    #     http.options('/')
     #
     def options: (String path, ?Hash[String, untyped] initheader) -> Net::HTTPResponse
 
@@ -1282,8 +1779,15 @@ module Net
     #   rdoc-file=lib/net/http.rb
     #   - propfind(path, body = nil, initheader = {'Depth' => '0'})
     # -->
-    # Sends a PROPFIND request to the `path` and gets a response, as an HTTPResponse
-    # object.
+    # Sends a PROPFIND request to the server; returns an instance of a subclass of
+    # Net::HTTPResponse.
+    #
+    # The request is based on the Net::HTTP::Propfind object created from string
+    # `path`, string `body`, and initial headers hash `initheader`.
+    #
+    #     data = '{"userId": 1, "id": 1, "title": "delectus aut autem", "completed": false}'
+    #     http = Net::HTTP.new(hostname)
+    #     http.propfind('/todos/1', data)
     #
     def propfind: (String path, ?untyped? body, ?Hash[String, untyped] initheader) -> Net::HTTPResponse
 
@@ -1291,8 +1795,14 @@ module Net
     #   rdoc-file=lib/net/http.rb
     #   - delete(path, initheader = {'Depth' => 'Infinity'})
     # -->
-    # Sends a DELETE request to the `path` and gets a response, as an HTTPResponse
-    # object.
+    # Sends a DELETE request to the server; returns an instance of a subclass of
+    # Net::HTTPResponse.
+    #
+    # The request is based on the Net::HTTP::Delete object created from string
+    # `path` and initial headers hash `initheader`.
+    #
+    #     http = Net::HTTP.new(hostname)
+    #     http.delete('/todos/1')
     #
     def delete: (String path, ?Hash[String, untyped] initheader) -> Net::HTTPResponse
 
@@ -1300,8 +1810,14 @@ module Net
     #   rdoc-file=lib/net/http.rb
     #   - move(path, initheader = nil)
     # -->
-    # Sends a MOVE request to the `path` and gets a response, as an HTTPResponse
-    # object.
+    # Sends a MOVE request to the server; returns an instance of a subclass of
+    # Net::HTTPResponse.
+    #
+    # The request is based on the Net::HTTP::Move object created from string `path`
+    # and initial headers hash `initheader`.
+    #
+    #     http = Net::HTTP.new(hostname)
+    #     http.move('/todos/1')
     #
     def move: (String path, ?Hash[String, untyped] initheader) -> Net::HTTPResponse
 
@@ -1309,8 +1825,14 @@ module Net
     #   rdoc-file=lib/net/http.rb
     #   - copy(path, initheader = nil)
     # -->
-    # Sends a COPY request to the `path` and gets a response, as an HTTPResponse
-    # object.
+    # Sends a COPY request to the server; returns an instance of a subclass of
+    # Net::HTTPResponse.
+    #
+    # The request is based on the Net::HTTP::Copy object created from string `path`
+    # and initial headers hash `initheader`.
+    #
+    #     http = Net::HTTP.new(hostname)
+    #     http.copy('/todos/1')
     #
     def copy: (String path, ?Hash[String, untyped] initheader) -> Net::HTTPResponse
 
@@ -1318,8 +1840,15 @@ module Net
     #   rdoc-file=lib/net/http.rb
     #   - mkcol(path, body = nil, initheader = nil)
     # -->
-    # Sends a MKCOL request to the `path` and gets a response, as an HTTPResponse
-    # object.
+    # Sends a MKCOL request to the server; returns an instance of a subclass of
+    # Net::HTTPResponse.
+    #
+    # The request is based on the Net::HTTP::Mkcol object created from string
+    # `path`, string `body`, and initial headers hash `initheader`.
+    #
+    #     data = '{"userId": 1, "id": 1, "title": "delectus aut autem", "completed": false}'
+    #     http.mkcol('/todos/1', data)
+    #     http = Net::HTTP.new(hostname)
     #
     def mkcol: (String path, ?untyped? body, ?Hash[String, untyped] initheader) -> Net::HTTPResponse
 
@@ -1327,8 +1856,14 @@ module Net
     #   rdoc-file=lib/net/http.rb
     #   - trace(path, initheader = nil)
     # -->
-    # Sends a TRACE request to the `path` and gets a response, as an HTTPResponse
-    # object.
+    # Sends a TRACE request to the server; returns an instance of a subclass of
+    # Net::HTTPResponse.
+    #
+    # The request is based on the Net::HTTP::Trace object created from string `path`
+    # and initial headers hash `initheader`.
+    #
+    #     http = Net::HTTP.new(hostname)
+    #     http.trace('/todos/1')
     #
     def trace: (String path, ?Hash[String, untyped] initheader) -> Net::HTTPResponse
 
@@ -1336,29 +1871,27 @@ module Net
     #   rdoc-file=lib/net/http.rb
     #   - request_get(path, initheader = nil) { |response| ... }
     # -->
-    # Sends a GET request to the `path`. Returns the response as a Net::HTTPResponse
+    # Sends a GET request to the server; forms the response into a Net::HTTPResponse
     # object.
     #
-    # When called with a block, passes an HTTPResponse object to the block. The body
-    # of the response will not have been read yet; the block can process it using
-    # HTTPResponse#read_body, if desired.
+    # The request is based on the Net::HTTP::Get object created from string `path`
+    # and initial headers hash `initheader`.
+    #
+    # With no block given, returns the response object:
     #
-    # Returns the response.
+    #     http = Net::HTTP.new(hostname)
+    #     http.request_get('/todos') # => #<Net::HTTPOK 200 OK readbody=true>
     #
-    # This method never raises Net::* exceptions.
+    # With a block given, calls the block with the response object and returns the
+    # response object:
     #
-    #     response = http.request_get('/index.html')
-    #     # The entity body is already read in this case.
-    #     p response['content-type']
-    #     puts response.body
+    #     http.request_get('/todos') do |res|
+    #       p res
+    #     end # => #<Net::HTTPOK 200 OK readbody=true>
     #
-    #     # Using a block
-    #     http.request_get('/index.html') {|response|
-    #       p response['content-type']
-    #       response.read_body do |str|   # read body now
-    #         print str
-    #       end
-    #     }
+    # Output:
+    #
+    #     #<Net::HTTPOK 200 OK readbody=false>
     #
     def request_get: (String path, ?Hash[String, untyped] initheader) ?{ (Net::HTTPResponse response) -> void } -> Net::HTTPResponse
 
@@ -1366,15 +1899,14 @@ module Net
     #   rdoc-file=lib/net/http.rb
     #   - request_head(path, initheader = nil, &block)
     # -->
-    # Sends a HEAD request to the `path` and returns the response as a
-    # Net::HTTPResponse object.
+    # Sends a HEAD request to the server; returns an instance of a subclass of
+    # Net::HTTPResponse.
     #
-    # Returns the response.
+    # The request is based on the Net::HTTP::Head object created from string `path`
+    # and initial headers hash `initheader`.
     #
-    # This method never raises Net::* exceptions.
-    #
-    #     response = http.request_head('/index.html')
-    #     p response['content-type']
+    #     http = Net::HTTP.new(hostname)
+    #     http.head('/todos/1') # => #<Net::HTTPOK 200 OK readbody=true>
     #
     def request_head: (String path, ?Hash[String, untyped] initheader) ?{ (Net::HTTPResponse response) -> void } -> Net::HTTPResponse
 
@@ -1382,31 +1914,28 @@ module Net
     #   rdoc-file=lib/net/http.rb
     #   - request_post(path, data, initheader = nil) { |response| ... }
     # -->
-    # Sends a POST request to the `path`.
+    # Sends a POST request to the server; forms the response into a
+    # Net::HTTPResponse object.
     #
-    # Returns the response as a Net::HTTPResponse object.
+    # The request is based on the Net::HTTP::Post object created from string `path`,
+    # string `data`, and initial headers hash `initheader`.
     #
-    # When called with a block, the block is passed an HTTPResponse object.  The
-    # body of that response will not have been read yet; the block can process it
-    # using HTTPResponse#read_body, if desired.
+    # With no block given, returns the response object:
     #
-    # Returns the response.
+    #     http = Net::HTTP.new(hostname)
+    #     http.post('/todos', 'xyzzy')
+    #     # => #<Net::HTTPCreated 201 Created readbody=true>
     #
-    # This method never raises Net::* exceptions.
+    # With a block given, calls the block with the response body and returns the
+    # response object:
     #
-    #     # example
-    #     response = http.request_post('/cgi-bin/nice.rb', 'datadatadata...')
-    #     p response.status
-    #     puts response.body          # body is already read in this case
+    #     http.post('/todos', 'xyzzy') do |res|
+    #       p res
+    #     end # => #<Net::HTTPCreated 201 Created readbody=true>
     #
-    #     # using block
-    #     http.request_post('/cgi-bin/nice.rb', 'datadatadata...') {|response|
-    #       p response.status
-    #       p response['content-type']
-    #       response.read_body do |str|   # read body now
-    #         print str
-    #       end
-    #     }
+    # Output:
+    #
+    #     "{\n  \"xyzzy\": \"\",\n  \"id\": 201\n}"
     #
     def request_post: (String path, String data, ?Hash[String, untyped] initheader) ?{ (Net::HTTPResponse response) -> void } -> Net::HTTPResponse
 
@@ -1439,15 +1968,24 @@ module Net
     #   rdoc-file=lib/net/http.rb
     #   - send_request(name, path, data = nil, header = nil)
     # -->
-    # Sends an HTTP request to the HTTP server. Also sends a DATA string if `data`
-    # is given.
+    # Sends an HTTP request to the server; returns an instance of a subclass of
+    # Net::HTTPResponse.
     #
-    # Returns a Net::HTTPResponse object.
+    # The request is based on the Net::HTTPRequest object created from string
+    # `path`, string `data`, and initial headers hash `header`. That object is an
+    # instance of the [subclass of
+    # Net::HTTPRequest](rdoc-ref:Net::HTTPRequest@Request+Subclasses), that
+    # corresponds to the given uppercase string `name`, which must be an [HTTP
+    # request method](https://en.wikipedia.org/wiki/HTTP#Request_methods) or a
+    # [WebDAV request method](https://en.wikipedia.org/wiki/WebDAV#Implementation).
     #
-    # This method never raises Net::* exceptions.
+    # Examples:
     #
-    #     response = http.send_request('GET', '/index.html')
-    #     puts response.body
+    #     http = Net::HTTP.new(hostname)
+    #     http.send_request('GET', '/todos/1')
+    #     # => #<Net::HTTPOK 200 OK readbody=true>
+    #     http.send_request('POST', '/todos', 'xyzzy')
+    #     # => #<Net::HTTPCreated 201 Created readbody=true>
     #
     def send_request: (String name, String path, ?String? data, ?Hash[String, untyped]? header) -> Net::HTTPResponse
 
@@ -1455,28 +1993,80 @@ module Net
     #   rdoc-file=lib/net/http.rb
     #   - request(req, body = nil) { |response| ... }
     # -->
-    # Sends an HTTPRequest object `req` to the HTTP server.
+    # Sends the given request `req` to the server; forms the response into a
+    # Net::HTTPResponse object.
+    #
+    # The given `req` must be an instance of a [subclass of
+    # Net::HTTPRequest](rdoc-ref:Net::HTTPRequest@Request+Subclasses). Argument
+    # `body` should be given only if needed for the request.
+    #
+    # With no block given, returns the response object:
+    #
+    #     http = Net::HTTP.new(hostname)
+    #
+    #     req = Net::HTTP::Get.new('/todos/1')
+    #     http.request(req)
+    #     # => #<Net::HTTPOK 200 OK readbody=true>
     #
-    # If `req` is a Net::HTTP::Post or Net::HTTP::Put request containing data, the
-    # data is also sent. Providing data for a Net::HTTP::Head or Net::HTTP::Get
-    # request results in an ArgumentError.
+    #     req = Net::HTTP::Post.new('/todos')
+    #     http.request(req, 'xyzzy')
+    #     # => #<Net::HTTPCreated 201 Created readbody=true>
     #
-    # Returns an HTTPResponse object.
+    # With a block given, calls the block with the response and returns the
+    # response:
     #
-    # When called with a block, passes an HTTPResponse object to the block. The body
-    # of the response will not have been read yet; the block can process it using
-    # HTTPResponse#read_body, if desired.
+    #     req = Net::HTTP::Get.new('/todos/1')
+    #     http.request(req) do |res|
+    #       p res
+    #     end # => #<Net::HTTPOK 200 OK readbody=true>
+    #
+    # Output:
     #
-    # This method never raises Net::* exceptions.
+    #     #<Net::HTTPOK 200 OK readbody=false>
     #
     def request: (Net::HTTPRequest req, ?String? body) ?{ (Net::HTTPResponse response) -> void } -> Net::HTTPResponse
   end
 
   # <!-- rdoc-file=lib/net/http/generic_request.rb -->
-  # HTTPGenericRequest is the parent of the Net::HTTPRequest class. Do not use
-  # this directly; use a subclass of Net::HTTPRequest.
+  # HTTPGenericRequest is the parent of the Net::HTTPRequest class.
+  #
+  # Do not use this directly; instead, use a subclass of Net::HTTPRequest.
+  #
+  # ## About the Examples
+  #
+  # Examples here assume that `net/http` has been required (which also requires
+  # `uri`):
+  #
+  #     require 'net/http'
+  #
+  # Many code examples here use these example websites:
+  #
+  # *   https://jsonplaceholder.typicode.com.
+  # *   http://example.com.
+  #
+  #
+  # Some examples also assume these variables:
+  #
+  #     uri = URI('https://jsonplaceholder.typicode.com/')
+  #     uri.freeze # Examples may not modify.
+  #     hostname = uri.hostname # => "jsonplaceholder.typicode.com"
+  #     path = uri.path         # => "/"
+  #     port = uri.port         # => 443
   #
-  # Mixes in the Net::HTTPHeader module to provide easier access to HTTP headers.
+  # So that example requests may be written as:
+  #
+  #     Net::HTTP.get(uri)
+  #     Net::HTTP.get(hostname, '/index.html')
+  #     Net::HTTP.start(hostname) do |http|
+  #       http.get('/todos/1')
+  #       http.get('/todos/2')
+  #     end
+  #
+  # An example that needs a modified URI first duplicates `uri`, then modifies the
+  # duplicate:
+  #
+  #     _uri = uri.dup
+  #     _uri.path = '/todos/1'
   #
   class HTTPGenericRequest
     include Net::HTTPHeader
@@ -1488,15 +2078,43 @@ module Net
     #
     def initialize: (String m, boolish reqbody, boolish resbody, URI::Generic | String uri_or_path, ?Hash[String, untyped] initheader) -> Net::HTTP
 
+    # <!-- rdoc-file=lib/net/http/generic_request.rb -->
+    # Returns the string method name for the request:
+    #
+    #     Net::HTTP::Get.new(uri).method  # => "GET"
+    #     Net::HTTP::Post.new(uri).method # => "POST"
+    #
     attr_reader method: String
 
+    # <!-- rdoc-file=lib/net/http/generic_request.rb -->
+    # Returns the string path for the request:
+    #
+    #     Net::HTTP::Get.new(uri).path # => "/"
+    #     Net::HTTP::Post.new('example.com').path # => "example.com"
+    #
     attr_reader path: String
 
+    # <!-- rdoc-file=lib/net/http/generic_request.rb -->
+    # Returns the URI object for the request, or `nil` if none:
+    #
+    #     Net::HTTP::Get.new(uri).uri
+    #     # => #<URI::HTTPS https://jsonplaceholder.typicode.com/>
+    #     Net::HTTP::Get.new('example.com').uri # => nil
+    #
     attr_reader uri: URI::Generic
 
     # <!-- rdoc-file=lib/net/http/generic_request.rb -->
-    # Automatically set to false if the user sets the Accept-Encoding header. This
-    # indicates they wish to handle Content-encoding in responses themselves.
+    # Returns `false` if the request's header `'Accept-Encoding'` has been set
+    # manually or deleted (indicating that the user intends to handle encoding in
+    # the response), `true` otherwise:
+    #
+    #     req = Net::HTTP::Get.new(uri) # => #<Net::HTTP::Get GET>
+    #     req['Accept-Encoding']        # => "gzip;q=1.0,deflate;q=0.6,identity;q=0.3"
+    #     req.decode_content            # => true
+    #     req['Accept-Encoding'] = 'foo'
+    #     req.decode_content            # => false
+    #     req.delete('Accept-Encoding')
+    #     req.decode_content            # => false
     #
     attr_reader decode_content: bool
 
@@ -1504,6 +2122,9 @@ module Net
     #   rdoc-file=lib/net/http/generic_request.rb
     #   - inspect()
     # -->
+    # Returns a string representation of the request:
+    #
+    #     Net::HTTP::Post.new(uri).inspect # => "#<Net::HTTP::Post POST>"
     #
     def inspect: () -> String
 
@@ -1513,6 +2134,10 @@ module Net
     #   rdoc-file=lib/net/http/generic_request.rb
     #   - request_body_permitted?()
     # -->
+    # Returns whether the request may have a body:
+    #
+    #     Net::HTTP::Post.new(uri).request_body_permitted? # => true
+    #     Net::HTTP::Get.new(uri).request_body_permitted?  # => false
     #
     def request_body_permitted?: () -> bool
 
@@ -1520,6 +2145,10 @@ module Net
     #   rdoc-file=lib/net/http/generic_request.rb
     #   - response_body_permitted?()
     # -->
+    # Returns whether the response may have a body:
+    #
+    #     Net::HTTP::Post.new(uri).response_body_permitted? # => true
+    #     Net::HTTP::Head.new(uri).response_body_permitted? # => false
     #
     def response_body_permitted?: () -> bool
 
@@ -1530,17 +2159,47 @@ module Net
     #
     def body_exist?: () -> bool
 
+    # <!-- rdoc-file=lib/net/http/generic_request.rb -->
+    # Returns the string body for the request, or `nil` if there is none:
+    #
+    #     req = Net::HTTP::Post.new(uri)
+    #     req.body # => nil
+    #     req.body = '{"title": "foo","body": "bar","userId": 1}'
+    #     req.body # => "{\"title\": \"foo\",\"body\": \"bar\",\"userId\": 1}"
+    # ----
     # <!--
     #   rdoc-file=lib/net/http/generic_request.rb
     #   - body=(str)
     # -->
+    # Sets the body for the request:
+    #
+    #     req = Net::HTTP::Post.new(uri)
+    #     req.body # => nil
+    #     req.body = '{"title": "foo","body": "bar","userId": 1}'
+    #     req.body # => "{\"title\": \"foo\",\"body\": \"bar\",\"userId\": 1}"
     #
     attr_accessor body: String?
 
+    # <!-- rdoc-file=lib/net/http/generic_request.rb -->
+    # Returns the body stream object for the request, or `nil` if there is none:
+    #
+    #     req = Net::HTTP::Post.new(uri)          # => #<Net::HTTP::Post POST>
+    #     req.body_stream                         # => nil
+    #     require 'stringio'
+    #     req.body_stream = StringIO.new('xyzzy') # => #<StringIO:0x0000027d1e5affa8>
+    #     req.body_stream                         # => #<StringIO:0x0000027d1e5affa8>
+    # ----
     # <!--
     #   rdoc-file=lib/net/http/generic_request.rb
     #   - body_stream=(input)
     # -->
+    # Sets the body stream for the request:
+    #
+    #     req = Net::HTTP::Post.new(uri)          # => #<Net::HTTP::Post POST>
+    #     req.body_stream                         # => nil
+    #     require 'stringio'
+    #     req.body_stream = StringIO.new('xyzzy') # => #<StringIO:0x0000027d1e5affa8>
+    #     req.body_stream                         # => #<StringIO:0x0000027d1e5affa8>
     #
     attr_accessor body_stream: untyped
   end
@@ -1594,9 +2253,10 @@ module Net
   #
   # Some examples also assume these variables:
   #
-  #     uri = URI('https://jsonplaceholder.typicode.com')
+  #     uri = URI('https://jsonplaceholder.typicode.com/')
   #     uri.freeze # Examples may not modify.
   #     hostname = uri.hostname # => "jsonplaceholder.typicode.com"
+  #     path = uri.path         # => "/"
   #     port = uri.port         # => 443
   #
   # So that example requests may be written as:
@@ -2327,18 +2987,37 @@ module Net
     #   rdoc-file=lib/net/http/header.rb
     #   - set_form_data(params, sep = '&')
     # -->
-    # 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](rdoc-ref:URI.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.
     #
@@ -2355,61 +3034,110 @@ module Net
     #   rdoc-file=lib/net/http/header.rb
     #   - set_form(params, enctype='application/x-www-form-urlencoded', formopt={})
     # -->
-    # Set an HTML form data set.
-    # `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.
+    # Stores form data to be used in a `POST` or `PUT` request.
     #
+    # The form data given in `params` consists of zero or more fields; each field
+    # is:
     #
+    # *   A scalar value.
+    # *   A name/value pair.
+    # *   An IO stream opened for reading.
     #
-    # Each item of params should respond to `each` and yield 2-3 arguments, or an
-    # array of 2-3 elements. The arguments yielded should be:
     #
-    # *   The name of the field.
-    # *   The value of the field, it should be a String or a File or IO-like.
-    # *   An options hash, supporting the following options (used only for file
-    #     uploads); entries:
+    # Argument `params` should be an
+    # [Enumerable](rdoc-ref:Enumerable@Enumerable+in+Ruby+Classes) (method
+    # `params.map` will be called), and is often an array or hash.
     #
-    #     *   `:filename`: The name of the file to use.
-    #     *   `:content_type`: The content type of the uploaded file.
+    # First, we set up a request:
     #
+    #     _uri = uri.dup
+    #     _uri.path ='/posts'
+    #     req = Net::HTTP::Post.new(_uri)
     #
+    # **Argument `params` As an Array**
     #
-    # 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.
+    # When `params` is an array, each of its elements is a subarray that defines a
+    # field; the subarray may contain:
     #
-    # 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.
+    # *   One string:
     #
-    # Example:
+    #         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 `'multipart/form-data'`:
+    #
+    #     *   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.
+    #
+    #
+    #         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')},
-    #                  "multipart/form-data",
-    #                  charset: "UTF-8",
-    #     )
     #
-    #     req.set_form([["f",
-    #                    File.open('/path/to/filename.bar'),
-    #                    {filename: "other-filename.foo"}
-    #                  ]],
-    #                  "multipart/form-data",
-    #     )
     #
-    # See also RFC 2388, RFC 2616, HTML 4.01, and HTML5
+    # The various forms may be mixed:
+    #
+    #     req.set_form(['foo', %w[bar 1], ['file', file]])
+    #
+    # **Argument `params` As a Hash**
+    #
+    # 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 `'multipart/form-data'`).
+    #
+    #
+    #
+    # 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
+    # `'Content-Type'`, and must be one of:
+    #
+    # *   `'application/x-www-form-urlencoded'` (the default).
+    # *   `'multipart/form-data'`; see [RFC
+    #     7578](https://www.rfc-editor.org/rfc/rfc7578).
+    #
+    #
+    # Optional argument `formopt` is a hash of options (applicable only when
+    # argument `enctype` is `'multipart/form-data'`) 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: (Hash[untyped, untyped] params, ?String enctype, ?Hash[untyped, untyped] formopt) -> void
 
@@ -2417,7 +3145,12 @@ module Net
     #   rdoc-file=lib/net/http/header.rb
     #   - basic_auth(account, password)
     # -->
-    # Set the Authorization: header for "Basic" authorization.
+    # Sets header `'Authorization'` using the given `account` and `password`
+    # strings:
+    #
+    #     req.basic_auth('my_account', 'my_password')
+    #     req['Authorization']
+    #     # => "Basic bXlfYWNjb3VudDpteV9wYXNzd29yZA=="
     #
     def basic_auth: (String account, String password) -> void
 
@@ -2425,7 +3158,12 @@ module Net
     #   rdoc-file=lib/net/http/header.rb
     #   - proxy_basic_auth(account, password)
     # -->
-    # Set Proxy-Authorization: header for "Basic" authorization.
+    # Sets header `'Proxy-Authorization'` using the given `account` and `password`
+    # strings:
+    #
+    #     req.proxy_basic_auth('my_account', 'my_password')
+    #     req['Proxy-Authorization']
+    #     # => "Basic bXlfYWNjb3VudDpteV9wYXNzd29yZA=="
     #
     def proxy_basic_auth: (String account, String password) -> void
 
@@ -2444,6 +3182,7 @@ module Net
     #   rdoc-file=lib/net/http/header.rb
     #   - connection_close?()
     # -->
+    # Returns whether the HTTP session is to be closed.
     #
     def connection_close?: () -> bool
 
@@ -2451,15 +3190,70 @@ module Net
     #   rdoc-file=lib/net/http/header.rb
     #   - connection_keep_alive?()
     # -->
+    # Returns whether the HTTP session is to be kept alive.
     #
     def connection_keep_alive?: () -> bool
   end
 
   # <!-- rdoc-file=lib/net/http/request.rb -->
-  # This class is the base class for Net::HTTP request classes; it wraps together
-  # the request path and the request headers.
+  # This class is the base class for Net::HTTP request classes. The class should
+  # not be used directly; instead you should use its subclasses, listed below.
+  #
+  # ## Creating a Request
   #
-  # The class should not be used directly; instead you should use its subclasses.
+  # An request object may be created with either a URI or a string hostname:
+  #
+  #     require 'net/http'
+  #     uri = URI('https://jsonplaceholder.typicode.com/')
+  #     req = Net::HTTP::Get.new(uri)          # => #<Net::HTTP::Get GET>
+  #     req = Net::HTTP::Get.new(uri.hostname) # => #<Net::HTTP::Get GET>
+  #
+  # And with any of the subclasses:
+  #
+  #     req = Net::HTTP::Head.new(uri) # => #<Net::HTTP::Head HEAD>
+  #     req = Net::HTTP::Post.new(uri) # => #<Net::HTTP::Post POST>
+  #     req = Net::HTTP::Put.new(uri)  # => #<Net::HTTP::Put PUT>
+  #     # ...
+  #
+  # The new instance is suitable for use as the argument to Net::HTTP#request.
+  #
+  # ## Request Headers
+  #
+  # A new request object has these header fields by default:
+  #
+  #     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"]}
+  #
+  # See:
+  #
+  # *   [Request header
+  #     Accept-Encoding](https://en.wikipedia.org/wiki/List_of_HTTP_header_fields#
+  #     Accept-Encoding) and [Compression and
+  #     Decompression](rdoc-ref:Net::HTTP@Compression+and+Decompression).
+  # *   [Request header
+  #     Accept](https://en.wikipedia.org/wiki/List_of_HTTP_header_fields#accept-re
+  #     quest-header).
+  # *   [Request header
+  #     User-Agent](https://en.wikipedia.org/wiki/List_of_HTTP_header_fields#user-
+  #     agent-request-header).
+  # *   [Request header
+  #     Host](https://en.wikipedia.org/wiki/List_of_HTTP_header_fields#host-reques
+  #     t-header).
+  #
+  #
+  # You can add headers or override default headers:
+  #
+  #     #   res = Net::HTTP::Get.new(uri, {'foo' => '0', 'bar' => '1'})
+  #
+  # This class (and therefore its subclasses) also includes (indirectly) module
+  # Net::HTTPHeader, which gives access to its [methods for setting
+  # headers](rdoc-ref:Net::HTTPHeader@Setters).
+  #
+  # ## Request Subclasses
   #
   # Subclasses for HTTP requests:
   #
@@ -2511,6 +3305,8 @@ module Net
   #       http.request(req)
   #     end
   #
+  # See [Request Headers](rdoc-ref:Net::HTTPRequest@Request+Headers).
+  #
   # Properties:
   #
   # *   Request body: optional.
@@ -2549,6 +3345,8 @@ module Net
   #       http.request(req)
   #     end
   #
+  # See [Request Headers](rdoc-ref:Net::HTTPRequest@Request+Headers).
+  #
   # Properties:
   #
   # *   Request body: optional.
@@ -2589,6 +3387,8 @@ module Net
   #       http.request(req)
   #     end
   #
+  # See [Request Headers](rdoc-ref:Net::HTTPRequest@Request+Headers).
+  #
   # Properties:
   #
   # *   Request body: yes.
@@ -2630,6 +3430,8 @@ module Net
   #       http.request(req)
   #     end
   #
+  # See [Request Headers](rdoc-ref:Net::HTTPRequest@Request+Headers).
+  #
   # Properties:
   #
   # *   Request body: yes.
@@ -2663,6 +3465,8 @@ module Net
   #       http.request(req)
   #     end
   #
+  # See [Request Headers](rdoc-ref:Net::HTTPRequest@Request+Headers).
+  #
   # Properties:
   #
   # *   Request body: optional.
@@ -2700,6 +3504,8 @@ module Net
   #       http.request(req)
   #     end
   #
+  # See [Request Headers](rdoc-ref:Net::HTTPRequest@Request+Headers).
+  #
   # Properties:
   #
   # *   Request body: optional.
@@ -2737,6 +3543,8 @@ module Net
   #       http.request(req)
   #     end
   #
+  # See [Request Headers](rdoc-ref:Net::HTTPRequest@Request+Headers).
+  #
   # Properties:
   #
   # *   Request body: no.
@@ -2777,6 +3585,8 @@ module Net
   #       http.request(req)
   #     end
   #
+  # See [Request Headers](rdoc-ref:Net::HTTPRequest@Request+Headers).
+  #
   # Properties:
   #
   # *   Request body: yes.
@@ -2813,6 +3623,8 @@ module Net
   #       http.request(req)
   #     end
   #
+  # See [Request Headers](rdoc-ref:Net::HTTPRequest@Request+Headers).
+  #
   # Related:
   #
   # *   Net::HTTP#propfind: sends `PROPFIND` request, returns response object.
@@ -2837,6 +3649,8 @@ module Net
   #       http.request(req)
   #     end
   #
+  # See [Request Headers](rdoc-ref:Net::HTTPRequest@Request+Headers).
+  #
   # Related:
   #
   # *   Net::HTTP#proppatch: sends `PROPPATCH` request, returns response object.
@@ -2861,6 +3675,8 @@ module Net
   #       http.request(req)
   #     end
   #
+  # See [Request Headers](rdoc-ref:Net::HTTPRequest@Request+Headers).
+  #
   # Related:
   #
   # *   Net::HTTP#mkcol: sends `MKCOL` request, returns response object.
@@ -2885,6 +3701,8 @@ module Net
   #       http.request(req)
   #     end
   #
+  # See [Request Headers](rdoc-ref:Net::HTTPRequest@Request+Headers).
+  #
   # Related:
   #
   # *   Net::HTTP#copy: sends `COPY` request, returns response object.
@@ -2909,6 +3727,8 @@ module Net
   #       http.request(req)
   #     end
   #
+  # See [Request Headers](rdoc-ref:Net::HTTPRequest@Request+Headers).
+  #
   # Related:
   #
   # *   Net::HTTP#move: sends `MOVE` request, returns response object.
@@ -2933,6 +3753,8 @@ module Net
   #       http.request(req)
   #     end
   #
+  # See [Request Headers](rdoc-ref:Net::HTTPRequest@Request+Headers).
+  #
   # Related:
   #
   # *   Net::HTTP#lock: sends `LOCK` request, returns response object.
@@ -2957,6 +3779,8 @@ module Net
   #       http.request(req)
   #     end
   #
+  # See [Request Headers](rdoc-ref:Net::HTTPRequest@Request+Headers).
+  #
   # Related:
   #
   # *   Net::HTTP#unlock: sends `UNLOCK` request, returns response object.
@@ -2970,7 +3794,7 @@ module Net
   end
 
   # <!-- rdoc-file=lib/net/http/response.rb -->
-  # This class is the base class for Net::HTTP request classes.
+  # This class is the base class for Net::HTTP response classes.
   #
   # ## About the Examples
   #
@@ -2987,9 +3811,10 @@ module Net
   #
   # Some examples also assume these variables:
   #
-  #     uri = URI('https://jsonplaceholder.typicode.com')
+  #     uri = URI('https://jsonplaceholder.typicode.com/')
   #     uri.freeze # Examples may not modify.
   #     hostname = uri.hostname # => "jsonplaceholder.typicode.com"
+  #     path = uri.path         # => "/"
   #     port = uri.port         # => 443
   #
   # So that example requests may be written as:
@@ -3254,19 +4079,20 @@ module Net
     #   rdoc-file=lib/net/http/response.rb
     #   - body()
     # -->
-    # Returns the full entity body.
+    # Returns the string response body; note that repeated calls for the unmodified
+    # body return a cached string:
     #
-    # Calling this method a second or subsequent time will return the string already
-    # read.
+    #     path = '/todos/1'
+    #     Net::HTTP.start(hostname) do |http|
+    #       res = http.get(path)
+    #       p res.body
+    #       p http.head(path).body # No body.
+    #     end
     #
-    #     http.request_get('/index.html') {|res|
-    #       puts res.body
-    #     }
+    # Output:
     #
-    #     http.request_get('/index.html') {|res|
-    #       p res.body.object_id   # 538149362
-    #       p res.body.object_id   # 538149362
-    #     }
+    #     "{\n  \"userId\": 1,\n  \"id\": 1,\n  \"title\": \"delectus aut autem\",\n  \"completed\": false\n}"
+    #     nil
     #
     def body: () -> String
 
@@ -3274,8 +4100,7 @@ module Net
     #   rdoc-file=lib/net/http/response.rb
     #   - body=(value)
     # -->
-    # Because it may be necessary to modify the body, Eg, decompression this method
-    # facilitates that.
+    # Sets the body of the response to the given value.
     #
     def body=: (untyped value) -> void
 
@@ -3387,6 +4212,9 @@ module Net
   # A `Continue` response indicates that the server has received the request
   # headers.
   #
+  # This class also includes (indirectly) module Net::HTTPHeader, which gives
+  # access to its [methods for getting headers](rdoc-ref:Net::HTTPHeader@Getters).
+  #
   # References:
   #
   # *   [Mozilla](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/100).
@@ -3403,6 +4231,9 @@ module Net
   # The <tt>Switching Protocol<tt> response indicates that the server has received
   # a request to switch protocols, and has agreed to do so.
   #
+  # This class also includes (indirectly) module Net::HTTPHeader, which gives
+  # access to its [methods for getting headers](rdoc-ref:Net::HTTPHeader@Getters).
+  #
   # References:
   #
   # *   [Mozilla](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/101).
@@ -3421,8 +4252,12 @@ module Net
   # The `Processing` response indicates that the server has received and is
   # processing the request, but no response is available yet.
   #
+  # This class also includes (indirectly) module Net::HTTPHeader, which gives
+  # access to its [methods for getting headers](rdoc-ref:Net::HTTPHeader@Getters).
+  #
   # References:
   #
+  # *   [RFC 2518](https://www.rfc-editor.org/rfc/rfc2518#section-10.1).
   # *   [Wikipedia](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#102).
   #
   class HTTPProcessing < HTTPInformation
@@ -3436,9 +4271,13 @@ module Net
   # request, and contains certain headers; the final response is not available
   # yet.
   #
+  # This class also includes (indirectly) module Net::HTTPHeader, which gives
+  # access to its [methods for getting headers](rdoc-ref:Net::HTTPHeader@Getters).
+  #
   # References:
   #
   # *   [Mozilla](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/103).
+  # *   [RFC 8297](https://www.rfc-editor.org/rfc/rfc8297.html#section-2).
   # *   [Wikipedia](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#103).
   #
   class HTTPEarlyHints < HTTPInformation
@@ -3449,8 +4288,16 @@ module Net
   # Response class for `OK` responses (status code 200).
   #
   # The `OK` response indicates that the server has received a request and has
-  # responded successfully. See [200
-  # OK](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#200).
+  # responded successfully.
+  #
+  # This class also includes (indirectly) module Net::HTTPHeader, which gives
+  # access to its [methods for getting headers](rdoc-ref:Net::HTTPHeader@Getters).
+  #
+  # References:
+  #
+  # *   [Mozilla](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200).
+  # *   [RFC 9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-200-ok).
+  # *   [Wikipedia](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#200).
   #
   class HTTPOK < HTTPSuccess
     HAS_BODY: bool
@@ -3460,8 +4307,16 @@ module Net
   # Response class for `Created` responses (status code 201).
   #
   # The `Created` response indicates that the server has received and has
-  # fulfilled a request to create a new resource. See [201
-  # Created](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#201).
+  # fulfilled a request to create a new resource.
+  #
+  # This class also includes (indirectly) module Net::HTTPHeader, which gives
+  # access to its [methods for getting headers](rdoc-ref:Net::HTTPHeader@Getters).
+  #
+  # References:
+  #
+  # *   [Mozilla](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/201).
+  # *   [RFC 9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-201-created).
+  # *   [Wikipedia](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#201).
   #
   class HTTPCreated < HTTPSuccess
     HAS_BODY: bool
@@ -3471,8 +4326,16 @@ module Net
   # Response class for `Accepted` responses (status code 202).
   #
   # The `Accepted` response indicates that the server has received and is
-  # processing a request, but the processing has not yet been completed. See [202
-  # Accepted](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#202).
+  # processing a request, but the processing has not yet been completed.
+  #
+  # This class also includes (indirectly) module Net::HTTPHeader, which gives
+  # access to its [methods for getting headers](rdoc-ref:Net::HTTPHeader@Getters).
+  #
+  # References:
+  #
+  # *   [Mozilla](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/202).
+  # *   [RFC 9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-202-accepted).
+  # *   [Wikipedia](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#202).
   #
   class HTTPAccepted < HTTPSuccess
     HAS_BODY: bool
@@ -3485,8 +4348,17 @@ module Net
   # The `Non-Authoritative Information` response indicates that the server is a
   # transforming proxy (such as a Web accelerator) that received a 200 OK response
   # from its origin, and is returning a modified version of the origin's response.
-  # See [203 Non-Authoritative
-  # Information](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#203).
+  #
+  # This class also includes (indirectly) module Net::HTTPHeader, which gives
+  # access to its [methods for getting headers](rdoc-ref:Net::HTTPHeader@Getters).
+  #
+  # References:
+  #
+  # *   [Mozilla](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/203).
+  # *   [RFC
+  #     9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-203-non-authoritati
+  #     ve-infor).
+  # *   [Wikipedia](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#203).
   #
   class HTTPNonAuthoritativeInformation < HTTPSuccess
     HAS_BODY: bool
@@ -3496,8 +4368,17 @@ module Net
   # Response class for `No Content` responses (status code 204).
   #
   # The `No Content` response indicates that the server successfully processed the
-  # request, and is not returning any content. See [204 No
-  # Content](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#204).
+  # request, and is not returning any content.
+  #
+  # This class also includes (indirectly) module Net::HTTPHeader, which gives
+  # access to its [methods for getting headers](rdoc-ref:Net::HTTPHeader@Getters).
+  #
+  # References:
+  #
+  # *   [Mozilla](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/204).
+  # *   [RFC
+  #     9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-204-no-content).
+  # *   [Wikipedia](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#204).
   #
   class HTTPNoContent < HTTPSuccess
     HAS_BODY: bool
@@ -3508,8 +4389,17 @@ module Net
   #
   # The `Reset Content` response indicates that the server successfully processed
   # the request, asks that the client reset its document view, and is not
-  # returning any content. See [205 Reset
-  # Content](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#205).
+  # returning any content.
+  #
+  # This class also includes (indirectly) module Net::HTTPHeader, which gives
+  # access to its [methods for getting headers](rdoc-ref:Net::HTTPHeader@Getters).
+  #
+  # References:
+  #
+  # *   [Mozilla](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/205).
+  # *   [RFC
+  #     9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-205-reset-content).
+  # *   [Wikipedia](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#205).
   #
   class HTTPResetContent < HTTPSuccess
     HAS_BODY: bool
@@ -3519,9 +4409,18 @@ module Net
   # Response class for `Partial Content` responses (status code 206).
   #
   # The `Partial Content` response indicates that the server is delivering only
-  # part of the resource (byte serving) due to a Range header in the request. See
-  # [206 Partial
-  # Content](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#206).
+  # part of the resource (byte serving) due to a Range header in the request.
+  #
+  # This class also includes (indirectly) module Net::HTTPHeader, which gives
+  # access to its [methods for getting headers](rdoc-ref:Net::HTTPHeader@Getters).
+  #
+  # References:
+  #
+  # *   [Mozilla](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/206).
+  # *   [RFC
+  #     9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-206-partial-content
+  #     ).
+  # *   [Wikipedia](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#206).
   #
   class HTTPPartialContent < HTTPSuccess
     HAS_BODY: bool
@@ -3532,8 +4431,15 @@ module Net
   #
   # The `Multi-Status (WebDAV)` response indicates that the server has received
   # the request, and that the message body can contain a number of separate
-  # response codes. See [207 Multi-Status
-  # (WebDAV)](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#207).
+  # response codes.
+  #
+  # This class also includes (indirectly) module Net::HTTPHeader, which gives
+  # access to its [methods for getting headers](rdoc-ref:Net::HTTPHeader@Getters).
+  #
+  # References:
+  #
+  # *   [RFC 4818](https://www.rfc-editor.org/rfc/rfc4918#section-11.1).
+  # *   [Wikipedia](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#207).
   #
   class HTTPMultiStatus < HTTPSuccess
     HAS_BODY: bool
@@ -3545,8 +4451,15 @@ module Net
   # The `Already Reported (WebDAV)` response indicates that the server has
   # received the request, and that the members of a DAV binding have already been
   # enumerated in a preceding part of the (multi-status) response, and are not
-  # being included again. See [208 Already Reported
-  # (WebDAV)](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#208).
+  # being included again.
+  #
+  # This class also includes (indirectly) module Net::HTTPHeader, which gives
+  # access to its [methods for getting headers](rdoc-ref:Net::HTTPHeader@Getters).
+  #
+  # References:
+  #
+  # *   [RFC 5842](https://www.rfc-editor.org/rfc/rfc5842.html#section-7.1).
+  # *   [Wikipedia](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#208).
   #
   class HTTPAlreadyReported < HTTPSuccess
     HAS_BODY: bool
@@ -3557,8 +4470,15 @@ module Net
   #
   # The `IM Used` response indicates that the server has fulfilled a request for
   # the resource, and the response is a representation of the result of one or
-  # more instance-manipulations applied to the current instance. See [226 IM
-  # Used](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#226).
+  # more instance-manipulations applied to the current instance.
+  #
+  # This class also includes (indirectly) module Net::HTTPHeader, which gives
+  # access to its [methods for getting headers](rdoc-ref:Net::HTTPHeader@Getters).
+  #
+  # References:
+  #
+  # *   [RFC 3229](https://www.rfc-editor.org/rfc/rfc3229.html#section-10.4.1).
+  # *   [Wikipedia](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#226).
   #
   class HTTPIMUsed < HTTPSuccess
     HAS_BODY: bool
@@ -3568,8 +4488,18 @@ module Net
   # Response class for `Multiple Choices` responses (status code 300).
   #
   # The `Multiple Choices` response indicates that the server offers multiple
-  # options for the resource from which the client may choose. See [300 Multiple
-  # Choices](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#300).
+  # options for the resource from which the client may choose.
+  #
+  # This class also includes (indirectly) module Net::HTTPHeader, which gives
+  # access to its [methods for getting headers](rdoc-ref:Net::HTTPHeader@Getters).
+  #
+  # References:
+  #
+  # *   [Mozilla](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/300).
+  # *   [RFC
+  #     9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-300-multiple-choice
+  #     s).
+  # *   [Wikipedia](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#300).
   #
   class HTTPMultipleChoices < HTTPRedirection
     HAS_BODY: bool
@@ -3579,8 +4509,18 @@ module Net
   # Response class for `Multiple Choices` responses (status code 300).
   #
   # The `Multiple Choices` response indicates that the server offers multiple
-  # options for the resource from which the client may choose. See [300 Multiple
-  # Choices](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#300).
+  # options for the resource from which the client may choose.
+  #
+  # This class also includes (indirectly) module Net::HTTPHeader, which gives
+  # access to its [methods for getting headers](rdoc-ref:Net::HTTPHeader@Getters).
+  #
+  # References:
+  #
+  # *   [Mozilla](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/300).
+  # *   [RFC
+  #     9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-300-multiple-choice
+  #     s).
+  # *   [Wikipedia](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#300).
   #
   HTTPMultipleChoice: HTTPMultipleChoices
 
@@ -3588,8 +4528,18 @@ module Net
   # Response class for `Moved Permanently` responses (status code 301).
   #
   # The `Moved Permanently` response indicates that links or records returning
-  # this response should be updated to use the given URL. See [301 Moved
-  # Permanently](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#301).
+  # this response should be updated to use the given URL.
+  #
+  # This class also includes (indirectly) module Net::HTTPHeader, which gives
+  # access to its [methods for getting headers](rdoc-ref:Net::HTTPHeader@Getters).
+  #
+  # References:
+  #
+  # *   [Mozilla](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/301).
+  # *   [RFC
+  #     9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-301-moved-permanent
+  #     ly).
+  # *   [Wikipedia](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#301).
   #
   class HTTPMovedPermanently < HTTPRedirection
     HAS_BODY: bool
@@ -3599,8 +4549,16 @@ module Net
   # Response class for `Found` responses (status code 302).
   #
   # The `Found` response indicates that the client should look at (browse to)
-  # another URL. See [302
-  # Found](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#302).
+  # another URL.
+  #
+  # This class also includes (indirectly) module Net::HTTPHeader, which gives
+  # access to its [methods for getting headers](rdoc-ref:Net::HTTPHeader@Getters).
+  #
+  # References:
+  #
+  # *   [Mozilla](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/302).
+  # *   [RFC 9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-302-found).
+  # *   [Wikipedia](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#302).
   #
   class HTTPFound < HTTPRedirection
     HAS_BODY: bool
@@ -3610,8 +4568,17 @@ module Net
   # Response class for `See Other` responses (status code 303).
   #
   # The response to the request can be found under another URI using the GET
-  # method. See [303 See
-  # Other](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#303).
+  # method.
+  #
+  # This class also includes (indirectly) module Net::HTTPHeader, which gives
+  # access to its [methods for getting headers](rdoc-ref:Net::HTTPHeader@Getters).
+  #
+  # References:
+  #
+  # *   [Mozilla](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/303).
+  # *   [RFC
+  #     9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-303-see-other).
+  # *   [Wikipedia](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#303).
   #
   class HTTPSeeOther < HTTPRedirection
     HAS_BODY: bool
@@ -3621,8 +4588,17 @@ module Net
   # Response class for `Not Modified` responses (status code 304).
   #
   # Indicates that the resource has not been modified since the version specified
-  # by the request headers. See [304 Not
-  # Modified](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#304).
+  # by the request headers.
+  #
+  # This class also includes (indirectly) module Net::HTTPHeader, which gives
+  # access to its [methods for getting headers](rdoc-ref:Net::HTTPHeader@Getters).
+  #
+  # References:
+  #
+  # *   [Mozilla](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/304).
+  # *   [RFC
+  #     9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-304-not-modified).
+  # *   [Wikipedia](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#304).
   #
   class HTTPNotModified < HTTPRedirection
     HAS_BODY: bool
@@ -3632,8 +4608,16 @@ module Net
   # Response class for `Use Proxy` responses (status code 305).
   #
   # The requested resource is available only through a proxy, whose address is
-  # provided in the response. See [305 Use
-  # Proxy](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#305).
+  # provided in the response.
+  #
+  # This class also includes (indirectly) module Net::HTTPHeader, which gives
+  # access to its [methods for getting headers](rdoc-ref:Net::HTTPHeader@Getters).
+  #
+  # References:
+  #
+  # *   [RFC
+  #     9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-305-use-proxy).
+  # *   [Wikipedia](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#305).
   #
   class HTTPUseProxy < HTTPRedirection
     HAS_BODY: bool
@@ -3643,8 +4627,18 @@ module Net
   # Response class for `Temporary Redirect` responses (status code 307).
   #
   # The request should be repeated with another URI; however, future requests
-  # should still use the original URI. See [307 Temporary
-  # Redirect](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#307).
+  # should still use the original URI.
+  #
+  # This class also includes (indirectly) module Net::HTTPHeader, which gives
+  # access to its [methods for getting headers](rdoc-ref:Net::HTTPHeader@Getters).
+  #
+  # References:
+  #
+  # *   [Mozilla](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/307).
+  # *   [RFC
+  #     9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-307-temporary-redir
+  #     ect).
+  # *   [Wikipedia](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#307).
   #
   class HTTPTemporaryRedirect < HTTPRedirection
     HAS_BODY: bool
@@ -3653,9 +4647,18 @@ module Net
   # <!-- rdoc-file=lib/net/http/responses.rb -->
   # Response class for `Permanent Redirect` responses (status code 308).
   #
-  # This and all future requests should be directed to the given URI. See [308
-  # Permanent
-  # Redirect](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#308).
+  # This and all future requests should be directed to the given URI.
+  #
+  # This class also includes (indirectly) module Net::HTTPHeader, which gives
+  # access to its [methods for getting headers](rdoc-ref:Net::HTTPHeader@Getters).
+  #
+  # References:
+  #
+  # *   [Mozilla](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/308).
+  # *   [RFC
+  #     9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-308-permanent-redir
+  #     ect).
+  # *   [Wikipedia](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#308).
   #
   class HTTPPermanentRedirect < HTTPRedirection
     HAS_BODY: bool
@@ -3665,8 +4668,17 @@ module Net
   # Response class for `Bad Request` responses (status code 400).
   #
   # The server cannot or will not process the request due to an apparent client
-  # error. See [400 Bad
-  # Request](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#400).
+  # error.
+  #
+  # This class also includes (indirectly) module Net::HTTPHeader, which gives
+  # access to its [methods for getting headers](rdoc-ref:Net::HTTPHeader@Getters).
+  #
+  # References:
+  #
+  # *   [Mozilla](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400).
+  # *   [RFC
+  #     9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-400-bad-request).
+  # *   [Wikipedia](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#400).
   #
   class HTTPBadRequest < HTTPClientError
     HAS_BODY: bool
@@ -3675,8 +4687,17 @@ module Net
   # <!-- rdoc-file=lib/net/http/responses.rb -->
   # Response class for `Unauthorized` responses (status code 401).
   #
-  # Authentication is required, but either was not provided or failed. See [401
-  # Unauthorized](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#401).
+  # Authentication is required, but either was not provided or failed.
+  #
+  # This class also includes (indirectly) module Net::HTTPHeader, which gives
+  # access to its [methods for getting headers](rdoc-ref:Net::HTTPHeader@Getters).
+  #
+  # References:
+  #
+  # *   [Mozilla](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401).
+  # *   [RFC
+  #     9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-401-unauthorized).
+  # *   [Wikipedia](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#401).
   #
   class HTTPUnauthorized < HTTPClientError
     HAS_BODY: bool
@@ -3685,8 +4706,18 @@ module Net
   # <!-- rdoc-file=lib/net/http/responses.rb -->
   # Response class for `Payment Required` responses (status code 402).
   #
-  # Reserved for future use. See [402 Payment
-  # Required](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#402).
+  # Reserved for future use.
+  #
+  # This class also includes (indirectly) module Net::HTTPHeader, which gives
+  # access to its [methods for getting headers](rdoc-ref:Net::HTTPHeader@Getters).
+  #
+  # References:
+  #
+  # *   [Mozilla](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/402).
+  # *   [RFC
+  #     9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-402-payment-require
+  #     d).
+  # *   [Wikipedia](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#402).
   #
   class HTTPPaymentRequired < HTTPClientError
     HAS_BODY: bool
@@ -3696,8 +4727,17 @@ module Net
   # Response class for `Forbidden` responses (status code 403).
   #
   # The request contained valid data and was understood by the server, but the
-  # server is refusing action. See [403
-  # Forbidden](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#403).
+  # server is refusing action.
+  #
+  # This class also includes (indirectly) module Net::HTTPHeader, which gives
+  # access to its [methods for getting headers](rdoc-ref:Net::HTTPHeader@Getters).
+  #
+  # References:
+  #
+  # *   [Mozilla](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/403).
+  # *   [RFC
+  #     9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-403-forbidden).
+  # *   [Wikipedia](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#403).
   #
   class HTTPForbidden < HTTPClientError
     HAS_BODY: bool
@@ -3707,8 +4747,16 @@ module Net
   # Response class for `Not Found` responses (status code 404).
   #
   # The requested resource could not be found but may be available in the future.
-  # See [404 Not
-  # Found](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#404).
+  #
+  # This class also includes (indirectly) module Net::HTTPHeader, which gives
+  # access to its [methods for getting headers](rdoc-ref:Net::HTTPHeader@Getters).
+  #
+  # References:
+  #
+  # *   [Mozilla](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404).
+  # *   [RFC
+  #     9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-404-not-found).
+  # *   [Wikipedia](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#404).
   #
   class HTTPNotFound < HTTPClientError
     HAS_BODY: bool
@@ -3717,9 +4765,18 @@ module Net
   # <!-- rdoc-file=lib/net/http/responses.rb -->
   # Response class for `Method Not Allowed` responses (status code 405).
   #
-  # The request method is not supported for the requested resource. See [405
-  # Method Not
-  # Allowed](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#405).
+  # The request method is not supported for the requested resource.
+  #
+  # This class also includes (indirectly) module Net::HTTPHeader, which gives
+  # access to its [methods for getting headers](rdoc-ref:Net::HTTPHeader@Getters).
+  #
+  # References:
+  #
+  # *   [Mozilla](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/405).
+  # *   [RFC
+  #     9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-405-method-not-allo
+  #     wed).
+  # *   [Wikipedia](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#405).
   #
   class HTTPMethodNotAllowed < HTTPClientError
     HAS_BODY: bool
@@ -3729,8 +4786,18 @@ module Net
   # Response class for `Not Acceptable` responses (status code 406).
   #
   # The requested resource is capable of generating only content that not
-  # acceptable according to the Accept headers sent in the request. See [406 Not
-  # Acceptable](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#406).
+  # acceptable according to the Accept headers sent in the request.
+  #
+  # This class also includes (indirectly) module Net::HTTPHeader, which gives
+  # access to its [methods for getting headers](rdoc-ref:Net::HTTPHeader@Getters).
+  #
+  # References:
+  #
+  # *   [Mozilla](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/406).
+  # *   [RFC
+  #     9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-406-not-acceptable)
+  #     .
+  # *   [Wikipedia](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#406).
   #
   class HTTPNotAcceptable < HTTPClientError
     HAS_BODY: bool
@@ -3740,9 +4807,18 @@ module Net
   # Response class for `Proxy Authentication Required` responses (status code
   # 407).
   #
-  # The client must first authenticate itself with the proxy. See [407 Proxy
-  # Authentication
-  # Required](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#407).
+  # The client must first authenticate itself with the proxy.
+  #
+  # This class also includes (indirectly) module Net::HTTPHeader, which gives
+  # access to its [methods for getting headers](rdoc-ref:Net::HTTPHeader@Getters).
+  #
+  # References:
+  #
+  # *   [Mozilla](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/407).
+  # *   [RFC
+  #     9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-407-proxy-authentic
+  #     ation-re).
+  # *   [Wikipedia](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#407).
   #
   class HTTPProxyAuthenticationRequired < HTTPClientError
     HAS_BODY: bool
@@ -3751,8 +4827,18 @@ module Net
   # <!-- rdoc-file=lib/net/http/responses.rb -->
   # Response class for `Request Timeout` responses (status code 408).
   #
-  # The server timed out waiting for the request. See [408 Request
-  # Timeout](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#408).
+  # The server timed out waiting for the request.
+  #
+  # This class also includes (indirectly) module Net::HTTPHeader, which gives
+  # access to its [methods for getting headers](rdoc-ref:Net::HTTPHeader@Getters).
+  #
+  # References:
+  #
+  # *   [Mozilla](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/408).
+  # *   [RFC
+  #     9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-408-request-timeout
+  #     ).
+  # *   [Wikipedia](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#408).
   #
   class HTTPRequestTimeout < HTTPClientError
     HAS_BODY: bool
@@ -3762,8 +4848,16 @@ module Net
   # Response class for `Conflict` responses (status code 409).
   #
   # The request could not be processed because of conflict in the current state of
-  # the resource. See [409
-  # Conflict](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#409).
+  # the resource.
+  #
+  # This class also includes (indirectly) module Net::HTTPHeader, which gives
+  # access to its [methods for getting headers](rdoc-ref:Net::HTTPHeader@Getters).
+  #
+  # References:
+  #
+  # *   [Mozilla](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/409).
+  # *   [RFC 9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-409-conflict).
+  # *   [Wikipedia](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#409).
   #
   class HTTPConflict < HTTPClientError
     HAS_BODY: bool
@@ -3773,8 +4867,16 @@ module Net
   # Response class for `Gone` responses (status code 410).
   #
   # The resource requested was previously in use but is no longer available and
-  # will not be available again. See [410
-  # Gone](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#410).
+  # will not be available again.
+  #
+  # This class also includes (indirectly) module Net::HTTPHeader, which gives
+  # access to its [methods for getting headers](rdoc-ref:Net::HTTPHeader@Getters).
+  #
+  # References:
+  #
+  # *   [Mozilla](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/410).
+  # *   [RFC 9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-410-gone).
+  # *   [Wikipedia](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#410).
   #
   class HTTPGone < HTTPClientError
     HAS_BODY: bool
@@ -3784,8 +4886,18 @@ module Net
   # Response class for `Length Required` responses (status code 411).
   #
   # The request did not specify the length of its content, which is required by
-  # the requested resource. See [411 Length
-  # Required](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#411).
+  # the requested resource.
+  #
+  # This class also includes (indirectly) module Net::HTTPHeader, which gives
+  # access to its [methods for getting headers](rdoc-ref:Net::HTTPHeader@Getters).
+  #
+  # References:
+  #
+  # *   [Mozilla](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/411).
+  # *   [RFC
+  #     9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-411-length-required
+  #     ).
+  # *   [Wikipedia](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#411).
   #
   class HTTPLengthRequired < HTTPClientError
     HAS_BODY: bool
@@ -3795,8 +4907,18 @@ module Net
   # Response class for `Precondition Failed` responses (status code 412).
   #
   # The server does not meet one of the preconditions specified in the request
-  # headers. See [412 Precondition
-  # Failed](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#412).
+  # headers.
+  #
+  # This class also includes (indirectly) module Net::HTTPHeader, which gives
+  # access to its [methods for getting headers](rdoc-ref:Net::HTTPHeader@Getters).
+  #
+  # References:
+  #
+  # *   [Mozilla](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/412).
+  # *   [RFC
+  #     9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-412-precondition-fa
+  #     iled).
+  # *   [Wikipedia](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#412).
   #
   class HTTPPreconditionFailed < HTTPClientError
     HAS_BODY: bool
@@ -3805,9 +4927,18 @@ module Net
   # <!-- rdoc-file=lib/net/http/responses.rb -->
   # Response class for `Payload Too Large` responses (status code 413).
   #
-  # The request is larger than the server is willing or able to process. See [413
-  # Payload Too
-  # Large](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#413).
+  # The request is larger than the server is willing or able to process.
+  #
+  # This class also includes (indirectly) module Net::HTTPHeader, which gives
+  # access to its [methods for getting headers](rdoc-ref:Net::HTTPHeader@Getters).
+  #
+  # References:
+  #
+  # *   [Mozilla](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/413).
+  # *   [RFC
+  #     9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-413-content-too-lar
+  #     ge).
+  # *   [Wikipedia](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#413).
   #
   class HTTPPayloadTooLarge < HTTPClientError
     HAS_BODY: bool
@@ -3816,8 +4947,17 @@ module Net
   # <!-- rdoc-file=lib/net/http/responses.rb -->
   # Response class for `URI Too Long` responses (status code 414).
   #
-  # The URI provided was too long for the server to process. See [414 URI Too
-  # Long](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#414).
+  # The URI provided was too long for the server to process.
+  #
+  # This class also includes (indirectly) module Net::HTTPHeader, which gives
+  # access to its [methods for getting headers](rdoc-ref:Net::HTTPHeader@Getters).
+  #
+  # References:
+  #
+  # *   [Mozilla](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/414).
+  # *   [RFC
+  #     9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-414-uri-too-long).
+  # *   [Wikipedia](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#414).
   #
   class HTTPURITooLong < HTTPClientError
     HAS_BODY: bool
@@ -3827,8 +4967,18 @@ module Net
   # Response class for `Unsupported Media Type` responses (status code 415).
   #
   # The request entity has a media type which the server or resource does not
-  # support. See [415 Unsupported Media
-  # Type](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#415).
+  # support.
+  #
+  # This class also includes (indirectly) module Net::HTTPHeader, which gives
+  # access to its [methods for getting headers](rdoc-ref:Net::HTTPHeader@Getters).
+  #
+  # References:
+  #
+  # *   [Mozilla](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/415).
+  # *   [RFC
+  #     9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-415-unsupported-med
+  #     ia-type).
+  # *   [Wikipedia](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#415).
   #
   class HTTPUnsupportedMediaType < HTTPClientError
     HAS_BODY: bool
@@ -3838,8 +4988,18 @@ module Net
   # Response class for `Range Not Satisfiable` responses (status code 416).
   #
   # The request entity has a media type which the server or resource does not
-  # support. See [416 Range Not
-  # Satisfiable](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#416).
+  # support.
+  #
+  # This class also includes (indirectly) module Net::HTTPHeader, which gives
+  # access to its [methods for getting headers](rdoc-ref:Net::HTTPHeader@Getters).
+  #
+  # References:
+  #
+  # *   [Mozilla](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/416).
+  # *   [RFC
+  #     9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-416-range-not-satis
+  #     fiable).
+  # *   [Wikipedia](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#416).
   #
   class HTTPRangeNotSatisfiable < HTTPClientError
     HAS_BODY: bool
@@ -3849,8 +5009,17 @@ module Net
   # Response class for `Expectation Failed` responses (status code 417).
   #
   # The server cannot meet the requirements of the Expect request-header field.
-  # See [417 Expectation
-  # Failed](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#417).
+  #
+  # This class also includes (indirectly) module Net::HTTPHeader, which gives
+  # access to its [methods for getting headers](rdoc-ref:Net::HTTPHeader@Getters).
+  #
+  # References:
+  #
+  # *   [Mozilla](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/417).
+  # *   [RFC
+  #     9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-417-expectation-fai
+  #     led).
+  # *   [Wikipedia](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#417).
   #
   class HTTPExpectationFailed < HTTPClientError
     HAS_BODY: bool
@@ -3860,8 +5029,16 @@ module Net
   # Response class for `Misdirected Request` responses (status code 421).
   #
   # The request was directed at a server that is not able to produce a response.
-  # See [421 Misdirected
-  # Request](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#421).
+  #
+  # This class also includes (indirectly) module Net::HTTPHeader, which gives
+  # access to its [methods for getting headers](rdoc-ref:Net::HTTPHeader@Getters).
+  #
+  # References:
+  #
+  # *   [RFC
+  #     9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-421-misdirected-req
+  #     uest).
+  # *   [Wikipedia](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#421).
   #
   class HTTPMisdirectedRequest < HTTPClientError
     HAS_BODY: bool
@@ -3870,8 +5047,18 @@ module Net
   # <!-- rdoc-file=lib/net/http/responses.rb -->
   # Response class for `Unprocessable Entity` responses (status code 422).
   #
-  # The request was well-formed but had semantic errors. See [422 Unprocessable
-  # Entity](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#422).
+  # The request was well-formed but had semantic errors.
+  #
+  # This class also includes (indirectly) module Net::HTTPHeader, which gives
+  # access to its [methods for getting headers](rdoc-ref:Net::HTTPHeader@Getters).
+  #
+  # References:
+  #
+  # *   [Mozilla](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422).
+  # *   [RFC
+  #     9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-422-unprocessable-c
+  #     ontent).
+  # *   [Wikipedia](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#422).
   #
   class HTTPUnprocessableEntity < HTTPClientError
     HAS_BODY: bool
@@ -3880,8 +5067,15 @@ module Net
   # <!-- rdoc-file=lib/net/http/responses.rb -->
   # Response class for `Locked (WebDAV)` responses (status code 423).
   #
-  # The requested resource is locked. See [423 Locked
-  # (WebDAV)](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#423).
+  # The requested resource is locked.
+  #
+  # This class also includes (indirectly) module Net::HTTPHeader, which gives
+  # access to its [methods for getting headers](rdoc-ref:Net::HTTPHeader@Getters).
+  #
+  # References:
+  #
+  # *   [RFC 4918](https://www.rfc-editor.org/rfc/rfc4918#section-11.3).
+  # *   [Wikipedia](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#423).
   #
   class HTTPLocked < HTTPClientError
     HAS_BODY: bool
@@ -3894,6 +5088,14 @@ module Net
   # failed. See [424 Failed Dependency
   # (WebDAV)](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#424).
   #
+  # This class also includes (indirectly) module Net::HTTPHeader, which gives
+  # access to its [methods for getting headers](rdoc-ref:Net::HTTPHeader@Getters).
+  #
+  # References:
+  #
+  # *   [RFC 4918](https://www.rfc-editor.org/rfc/rfc4918#section-11.4).
+  # *   [Wikipedia](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#424).
+  #
   class HTTPFailedDependency < HTTPClientError
     HAS_BODY: bool
   end
@@ -3902,8 +5104,17 @@ module Net
   # Response class for `Upgrade Required` responses (status code 426).
   #
   # The client should switch to the protocol given in the Upgrade header field.
-  # See [426 Upgrade
-  # Required](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#426).
+  #
+  # This class also includes (indirectly) module Net::HTTPHeader, which gives
+  # access to its [methods for getting headers](rdoc-ref:Net::HTTPHeader@Getters).
+  #
+  # References:
+  #
+  # *   [Mozilla](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/426).
+  # *   [RFC
+  #     9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-426-upgrade-require
+  #     d).
+  # *   [Wikipedia](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#426).
   #
   class HTTPUpgradeRequired < HTTPClientError
     HAS_BODY: bool
@@ -3912,9 +5123,16 @@ module Net
   # <!-- rdoc-file=lib/net/http/responses.rb -->
   # Response class for `Precondition Required` responses (status code 428).
   #
-  # The origin server requires the request to be conditional. See [428
-  # Precondition
-  # Required](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#428).
+  # The origin server requires the request to be conditional.
+  #
+  # This class also includes (indirectly) module Net::HTTPHeader, which gives
+  # access to its [methods for getting headers](rdoc-ref:Net::HTTPHeader@Getters).
+  #
+  # References:
+  #
+  # *   [Mozilla](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/428).
+  # *   [RFC 6585](https://www.rfc-editor.org/rfc/rfc6585#section-3).
+  # *   [Wikipedia](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#428).
   #
   class HTTPPreconditionRequired < HTTPClientError
     HAS_BODY: bool
@@ -3923,8 +5141,16 @@ module Net
   # <!-- rdoc-file=lib/net/http/responses.rb -->
   # Response class for `Too Many Requests` responses (status code 429).
   #
-  # The user has sent too many requests in a given amount of time. See [429 Too
-  # Many Requests](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#429).
+  # The user has sent too many requests in a given amount of time.
+  #
+  # This class also includes (indirectly) module Net::HTTPHeader, which gives
+  # access to its [methods for getting headers](rdoc-ref:Net::HTTPHeader@Getters).
+  #
+  # References:
+  #
+  # *   [Mozilla](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429).
+  # *   [RFC 6585](https://www.rfc-editor.org/rfc/rfc6585#section-4).
+  # *   [Wikipedia](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#429).
   #
   class HTTPTooManyRequests < HTTPClientError
     HAS_BODY: bool
@@ -3935,8 +5161,16 @@ module Net
   # 431).
   #
   # An individual header field is too large, or all the header fields
-  # collectively, are too large. See [431 Request Header Fields Too
-  # Large](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#431).
+  # collectively, are too large.
+  #
+  # This class also includes (indirectly) module Net::HTTPHeader, which gives
+  # access to its [methods for getting headers](rdoc-ref:Net::HTTPHeader@Getters).
+  #
+  # References:
+  #
+  # *   [Mozilla](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/431).
+  # *   [RFC 6585](https://www.rfc-editor.org/rfc/rfc6585#section-5).
+  # *   [Wikipedia](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#431).
   #
   class HTTPRequestHeaderFieldsTooLarge < HTTPClientError
     HAS_BODY: bool
@@ -3947,9 +5181,16 @@ module Net
   # 451).
   #
   # A server operator has received a legal demand to deny access to a resource or
-  # to a set of resources that includes the requested resource. See [451
-  # Unavailable For Legal
-  # Reasons](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#451).
+  # to a set of resources that includes the requested resource.
+  #
+  # This class also includes (indirectly) module Net::HTTPHeader, which gives
+  # access to its [methods for getting headers](rdoc-ref:Net::HTTPHeader@Getters).
+  #
+  # References:
+  #
+  # *   [Mozilla](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/451).
+  # *   [RFC 7725](https://www.rfc-editor.org/rfc/rfc7725.html#section-3).
+  # *   [Wikipedia](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#451).
   #
   class HTTPUnavailableForLegalReasons < HTTPClientError
     HAS_BODY: bool
@@ -3959,8 +5200,18 @@ module Net
   # Response class for `Internal Server Error` responses (status code 500).
   #
   # An unexpected condition was encountered and no more specific message is
-  # suitable. See [500 Internal Server
-  # Error](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#500).
+  # suitable.
+  #
+  # This class also includes (indirectly) module Net::HTTPHeader, which gives
+  # access to its [methods for getting headers](rdoc-ref:Net::HTTPHeader@Getters).
+  #
+  # References:
+  #
+  # *   [Mozilla](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500).
+  # *   [RFC
+  #     9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-500-internal-server
+  #     -error).
+  # *   [Wikipedia](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#500).
   #
   class HTTPInternalServerError < HTTPServerError
     HAS_BODY: bool
@@ -3970,8 +5221,18 @@ module Net
   # Response class for `Not Implemented` responses (status code 501).
   #
   # The server either does not recognize the request method, or it lacks the
-  # ability to fulfil the request. See [501 Not
-  # Implemented](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#501).
+  # ability to fulfil the request.
+  #
+  # This class also includes (indirectly) module Net::HTTPHeader, which gives
+  # access to its [methods for getting headers](rdoc-ref:Net::HTTPHeader@Getters).
+  #
+  # References:
+  #
+  # *   [Mozilla](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/501).
+  # *   [RFC
+  #     9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-501-not-implemented
+  #     ).
+  # *   [Wikipedia](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#501).
   #
   class HTTPNotImplemented < HTTPServerError
     HAS_BODY: bool
@@ -3981,8 +5242,17 @@ module Net
   # Response class for `Bad Gateway` responses (status code 502).
   #
   # The server was acting as a gateway or proxy and received an invalid response
-  # from the upstream server. See [502 Bad
-  # Gateway](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#502).
+  # from the upstream server.
+  #
+  # This class also includes (indirectly) module Net::HTTPHeader, which gives
+  # access to its [methods for getting headers](rdoc-ref:Net::HTTPHeader@Getters).
+  #
+  # References:
+  #
+  # *   [Mozilla](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/502).
+  # *   [RFC
+  #     9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-502-bad-gateway).
+  # *   [Wikipedia](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#502).
   #
   class HTTPBadGateway < HTTPServerError
     HAS_BODY: bool
@@ -3992,8 +5262,18 @@ module Net
   # Response class for `Service Unavailable` responses (status code 503).
   #
   # The server cannot handle the request (because it is overloaded or down for
-  # maintenance). See [503 Service
-  # Unavailable](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#503).
+  # maintenance).
+  #
+  # This class also includes (indirectly) module Net::HTTPHeader, which gives
+  # access to its [methods for getting headers](rdoc-ref:Net::HTTPHeader@Getters).
+  #
+  # References:
+  #
+  # *   [Mozilla](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/503).
+  # *   [RFC
+  #     9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-503-service-unavail
+  #     able).
+  # *   [Wikipedia](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#503).
   #
   class HTTPServiceUnavailable < HTTPServerError
     HAS_BODY: bool
@@ -4003,8 +5283,18 @@ module Net
   # Response class for `Gateway Timeout` responses (status code 504).
   #
   # The server was acting as a gateway or proxy and did not receive a timely
-  # response from the upstream server. See [504 Gateway
-  # Timeout](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#504).
+  # response from the upstream server.
+  #
+  # This class also includes (indirectly) module Net::HTTPHeader, which gives
+  # access to its [methods for getting headers](rdoc-ref:Net::HTTPHeader@Getters).
+  #
+  # References:
+  #
+  # *   [Mozilla](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/504).
+  # *   [RFC
+  #     9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-504-gateway-timeout
+  #     ).
+  # *   [Wikipedia](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#504).
   #
   class HTTPGatewayTimeout < HTTPServerError
     HAS_BODY: bool
@@ -4013,9 +5303,18 @@ module Net
   # <!-- rdoc-file=lib/net/http/responses.rb -->
   # Response class for `HTTP Version Not Supported` responses (status code 505).
   #
-  # The server does not support the HTTP version used in the request. See [505
-  # HTTP Version Not
-  # Supported](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#505).
+  # The server does not support the HTTP version used in the request.
+  #
+  # This class also includes (indirectly) module Net::HTTPHeader, which gives
+  # access to its [methods for getting headers](rdoc-ref:Net::HTTPHeader@Getters).
+  #
+  # References:
+  #
+  # *   [Mozilla](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/505).
+  # *   [RFC
+  #     9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-505-http-version-no
+  #     t-suppor).
+  # *   [Wikipedia](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#505).
   #
   class HTTPVersionNotSupported < HTTPServerError
     HAS_BODY: bool
@@ -4025,8 +5324,16 @@ module Net
   # Response class for `Variant Also Negotiates` responses (status code 506).
   #
   # Transparent content negotiation for the request results in a circular
-  # reference. See [506 Variant Also
-  # Negotiates](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#506).
+  # reference.
+  #
+  # This class also includes (indirectly) module Net::HTTPHeader, which gives
+  # access to its [methods for getting headers](rdoc-ref:Net::HTTPHeader@Getters).
+  #
+  # References:
+  #
+  # *   [Mozilla](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/506).
+  # *   [RFC 2295](https://www.rfc-editor.org/rfc/rfc2295#section-8.1).
+  # *   [Wikipedia](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#506).
   #
   class HTTPVariantAlsoNegotiates < HTTPServerError
     HAS_BODY: bool
@@ -4037,8 +5344,16 @@ module Net
   # 507).
   #
   # The server is unable to store the representation needed to complete the
-  # request. See [507 Insufficient Storage
-  # (WebDAV)](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#507).
+  # request.
+  #
+  # This class also includes (indirectly) module Net::HTTPHeader, which gives
+  # access to its [methods for getting headers](rdoc-ref:Net::HTTPHeader@Getters).
+  #
+  # References:
+  #
+  # *   [Mozilla](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/507).
+  # *   [RFC 4918](https://www.rfc-editor.org/rfc/rfc4918#section-11.5).
+  # *   [Wikipedia](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#507).
   #
   class HTTPInsufficientStorage < HTTPServerError
     HAS_BODY: bool
@@ -4047,9 +5362,16 @@ module Net
   # <!-- rdoc-file=lib/net/http/responses.rb -->
   # Response class for `Loop Detected (WebDAV)` responses (status code 508).
   #
-  # The server detected an infinite loop while processing the request. See [508
-  # Loop Detected
-  # (WebDAV)](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#508).
+  # The server detected an infinite loop while processing the request.
+  #
+  # This class also includes (indirectly) module Net::HTTPHeader, which gives
+  # access to its [methods for getting headers](rdoc-ref:Net::HTTPHeader@Getters).
+  #
+  # References:
+  #
+  # *   [Mozilla](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/508).
+  # *   [RFC 5942](https://www.rfc-editor.org/rfc/rfc5842.html#section-7.2).
+  # *   [Wikipedia](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#508).
   #
   class HTTPLoopDetected < HTTPServerError
     HAS_BODY: bool
@@ -4059,8 +5381,15 @@ module Net
   # Response class for `Not Extended` responses (status code 510).
   #
   # Further extensions to the request are required for the server to fulfill it.
-  # See [510 Not
-  # Extended](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#510).
+  #
+  # This class also includes (indirectly) module Net::HTTPHeader, which gives
+  # access to its [methods for getting headers](rdoc-ref:Net::HTTPHeader@Getters).
+  #
+  # References:
+  #
+  # *   [Mozilla](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/510).
+  # *   [RFC 2774](https://www.rfc-editor.org/rfc/rfc2774.html#section-7).
+  # *   [Wikipedia](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#510).
   #
   class HTTPNotExtended < HTTPServerError
     HAS_BODY: bool
@@ -4070,16 +5399,23 @@ module Net
   # Response class for `Network Authentication Required` responses (status code
   # 511).
   #
-  # The client needs to authenticate to gain network access. See [511 Network
-  # Authentication
-  # Required](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#511).
+  # The client needs to authenticate to gain network access.
+  #
+  # This class also includes (indirectly) module Net::HTTPHeader, which gives
+  # access to its [methods for getting headers](rdoc-ref:Net::HTTPHeader@Getters).
+  #
+  # References:
+  #
+  # *   [Mozilla](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/511).
+  # *   [RFC 6585](https://www.rfc-editor.org/rfc/rfc6585#section-6).
+  # *   [Wikipedia](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#511).
   #
   class HTTPNetworkAuthenticationRequired < HTTPServerError
     HAS_BODY: bool
   end
 
   # <!-- rdoc-file=lib/net/http/response.rb -->
-  # This class is the base class for Net::HTTP request classes.
+  # This class is the base class for Net::HTTP response classes.
   #
   # ## About the Examples
   #
@@ -4096,9 +5432,10 @@ module Net
   #
   # Some examples also assume these variables:
   #
-  #     uri = URI('https://jsonplaceholder.typicode.com')
+  #     uri = URI('https://jsonplaceholder.typicode.com/')
   #     uri.freeze # Examples may not modify.
   #     hostname = uri.hostname # => "jsonplaceholder.typicode.com"
+  #     path = uri.path         # => "/"
   #     port = uri.port         # => 443
   #
   # So that example requests may be written as: