[DOC] Enhanced RDoc for request headers (#120)

lib/net/http/request.rb

@@ -1,10 +1,55 @@
 # frozen_string_literal: false
 
-# 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.
+# instead you should use its subclasses, listed below.
+#
+# == Creating a Request
+#
+# 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-request-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-request-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:
 #

lib/net/http/requests.rb

@@ -13,7 +13,7 @@
 #     http.request(req)
 #   end
 #
-# :include: doc/net-http/included_setters.rdoc
+# See {Request Headers}[rdoc-ref:Net::HTTPRequest@Request+Headers].
 #
 # Properties:
 #
@@ -45,7 +45,7 @@ class Net::HTTP::Get < Net::HTTPRequest
 #     http.request(req)
 #   end
 #
-# :include: doc/net-http/included_setters.rdoc
+# See {Request Headers}[rdoc-ref:Net::HTTPRequest@Request+Headers].
 #
 # Properties:
 #
@@ -79,7 +79,7 @@ class Net::HTTP::Head < Net::HTTPRequest
 #     http.request(req)
 #   end
 #
-# :include: doc/net-http/included_setters.rdoc
+# See {Request Headers}[rdoc-ref:Net::HTTPRequest@Request+Headers].
 #
 # Properties:
 #
@@ -114,7 +114,7 @@ class Net::HTTP::Post < Net::HTTPRequest
 #     http.request(req)
 #   end
 #
-# :include: doc/net-http/included_setters.rdoc
+# See {Request Headers}[rdoc-ref:Net::HTTPRequest@Request+Headers].
 #
 # Properties:
 #
@@ -142,7 +142,7 @@ class Net::HTTP::Put < Net::HTTPRequest
 #     http.request(req)
 #   end
 #
-# :include: doc/net-http/included_setters.rdoc
+# See {Request Headers}[rdoc-ref:Net::HTTPRequest@Request+Headers].
 #
 # Properties:
 #
@@ -173,7 +173,7 @@ class Net::HTTP::Delete < Net::HTTPRequest
 #     http.request(req)
 #   end
 #
-# :include: doc/net-http/included_setters.rdoc
+# See {Request Headers}[rdoc-ref:Net::HTTPRequest@Request+Headers].
 #
 # Properties:
 #
@@ -204,7 +204,7 @@ class Net::HTTP::Options < Net::HTTPRequest
 #     http.request(req)
 #   end
 #
-# :include: doc/net-http/included_setters.rdoc
+# See {Request Headers}[rdoc-ref:Net::HTTPRequest@Request+Headers].
 #
 # Properties:
 #
@@ -238,7 +238,7 @@ class Net::HTTP::Trace < Net::HTTPRequest
 #     http.request(req)
 #   end
 #
-# :include: doc/net-http/included_setters.rdoc
+# See {Request Headers}[rdoc-ref:Net::HTTPRequest@Request+Headers].
 #
 # Properties:
 #
@@ -273,7 +273,7 @@ class Net::HTTP::Patch < Net::HTTPRequest
 #     http.request(req)
 #   end
 #
-# :include: doc/net-http/included_setters.rdoc
+# See {Request Headers}[rdoc-ref:Net::HTTPRequest@Request+Headers].
 #
 # Related:
 #
@@ -296,7 +296,7 @@ class Net::HTTP::Propfind < Net::HTTPRequest
 #     http.request(req)
 #   end
 #
-# :include: doc/net-http/included_setters.rdoc
+# See {Request Headers}[rdoc-ref:Net::HTTPRequest@Request+Headers].
 #
 # Related:
 #
@@ -319,7 +319,7 @@ class Net::HTTP::Proppatch < Net::HTTPRequest
 #     http.request(req)
 #   end
 #
-# :include: doc/net-http/included_setters.rdoc
+# See {Request Headers}[rdoc-ref:Net::HTTPRequest@Request+Headers].
 #
 # Related:
 #
@@ -342,7 +342,7 @@ class Net::HTTP::Mkcol < Net::HTTPRequest
 #     http.request(req)
 #   end
 #
-# :include: doc/net-http/included_setters.rdoc
+# See {Request Headers}[rdoc-ref:Net::HTTPRequest@Request+Headers].
 #
 # Related:
 #
@@ -365,7 +365,7 @@ class Net::HTTP::Copy < Net::HTTPRequest
 #     http.request(req)
 #   end
 #
-# :include: doc/net-http/included_setters.rdoc
+# See {Request Headers}[rdoc-ref:Net::HTTPRequest@Request+Headers].
 #
 # Related:
 #
@@ -388,7 +388,7 @@ class Net::HTTP::Move < Net::HTTPRequest
 #     http.request(req)
 #   end
 #
-# :include: doc/net-http/included_setters.rdoc
+# See {Request Headers}[rdoc-ref:Net::HTTPRequest@Request+Headers].
 #
 # Related:
 #
@@ -411,7 +411,7 @@ class Net::HTTP::Lock < Net::HTTPRequest
 #     http.request(req)
 #   end
 #
-# :include: doc/net-http/included_setters.rdoc
+# See {Request Headers}[rdoc-ref:Net::HTTPRequest@Request+Headers].
 #
 # Related:
 #