diff --git a/lib/net/http.rb b/lib/net/http.rb
index 521f576fbce75c..89277ca49d86b9 100644
--- a/lib/net/http.rb
+++ b/lib/net/http.rb
@@ -173,7 +173,7 @@ class HTTPHeaderSyntaxError < StandardError; end
   # {Request Fields}[https://en.wikipedia.org/wiki/List_of_HTTP_header_fields#Request_fields].
   # A host may also accept other custom fields.
   #
-  # == Sessions
+  # == \HTTP Sessions
   #
   # A _session_ is a connection between a server (host) and a client that:
   #
@@ -454,6 +454,271 @@ class HTTPHeaderSyntaxError < StandardError; end
   # - 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 <tt>Content-Length</tt> headers.
+  # - {:ignore_eof=}[rdoc-ref:Net::HTTP#ignore_eof=]:
+  #   Sets whether to ignore end-of-file when reading a response body
+  #   with <tt>Content-Length</tt> 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:
@@ -1494,7 +1759,7 @@ def HTTP.Proxy(p_addr = :ENV, p_port = nil, p_user = nil, p_pass = nil) #:nodoc:
     end
 
     class << HTTP
-      # 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 proxy_class?
         defined?(@is_proxy_class) ? @is_proxy_class : false
       end
diff --git a/lib/net/http/net-http.gemspec b/lib/net/http/net-http.gemspec
index a7f122fc0ecaa4..b07a0b6039ba04 100644
--- a/lib/net/http/net-http.gemspec
+++ b/lib/net/http/net-http.gemspec
@@ -2,9 +2,14 @@
 
 name = File.basename(__FILE__, ".gemspec")
 version = ["lib", Array.new(name.count("-")+1, "..").join("/")].find do |dir|
-  break File.foreach(File.join(__dir__, dir, "#{name.tr('-', '/')}.rb")) do |line|
-    /^\s*VERSION\s*=\s*"(.*)"/ =~ line and break $1
-  end rescue nil
+  file = File.join(__dir__, dir, "#{name.tr('-', '/')}.rb")
+  begin
+    break File.foreach(file, mode: "rb") do |line|
+      /^\s*VERSION\s*=\s*"(.*)"/ =~ line and break $1
+    end
+  rescue SystemCallError
+    next
+  end
 end
 
 Gem::Specification.new do |spec|
@@ -25,7 +30,7 @@ Gem::Specification.new do |spec|
   # Specify which files should be added to the gem when it is released.
   # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
   spec.files         = Dir.chdir(File.expand_path('..', __FILE__)) do
-    `git ls-files -z 2>/dev/null`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+    `git ls-files -z 2>/dev/null`.split("\x0").reject { |f| f.match(%r{\A(?:(?:test|spec|features)/|\.git)}) }
   end
   spec.bindir        = "exe"
   spec.require_paths = ["lib"]
diff --git a/lib/net/http/response.rb b/lib/net/http/response.rb
index 90c425b1a7387c..1d83935c105960 100644
--- a/lib/net/http/response.rb
+++ b/lib/net/http/response.rb
@@ -224,13 +224,32 @@ def initialize(httpv, code, msg)   #:nodoc: internal use only
   # Accept-Encoding header from the user.
   attr_accessor :decode_content
 
-  # The encoding to use for the response body. If Encoding, use that encoding.
-  # If other true value, attempt to detect the appropriate encoding, and use
-  # that.
+  # Returns the value set by body_encoding=, or +false+ if none;
+  # see #body_encoding=.
   attr_reader :body_encoding
 
-  # Set the encoding to use for the response body.  If given a String, find
-  # the related Encoding.
+  # Sets the encoding that should be used when reading the body:
+  #
+  # - If the given value is an Encoding object, that encoding will be used.
+  # - Otherwise if the value is a string, the value of
+  #   {Encoding#find(value)}[rdoc-ref:Encoding.find]
+  #   will be used.
+  # - Otherwise an encoding will be deduced from the body itself.
+  #
+  # Examples:
+  #
+  #   http = Net::HTTP.new(hostname)
+  #   req = Net::HTTP::Get.new('/')
+  #
+  #   http.request(req) do |res|
+  #     p res.body.encoding # => #<Encoding:ASCII-8BIT>
+  #   end
+  #
+  #   http.request(req) do |res|
+  #     res.body_encoding = "UTF-8"
+  #     p res.body.encoding # => #<Encoding:UTF-8>
+  #   end
+  #
   def body_encoding=(value)
     value = Encoding.find(value) if value.is_a?(String)
     @body_encoding = value
@@ -362,26 +381,26 @@ def read_body(dest = nil, &block)
     @body
   end
 
-  # 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
     read_body()
   end
 
-  # 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=(value)
     @body = value
   end
diff --git a/version.h b/version.h
index 4ed4774319b394..9cf23edbb0a9a3 100644
--- a/version.h
+++ b/version.h
@@ -11,7 +11,7 @@
 # define RUBY_VERSION_MINOR RUBY_API_VERSION_MINOR
 #define RUBY_VERSION_TEENY 2
 #define RUBY_RELEASE_DATE RUBY_RELEASE_YEAR_STR"-"RUBY_RELEASE_MONTH_STR"-"RUBY_RELEASE_DAY_STR
-#define RUBY_PATCHLEVEL 141
+#define RUBY_PATCHLEVEL 142
 
 #include "ruby/version.h"
 #include "ruby/internal/abi.h"