From b4eb8a79324d4817e51bd39c75a6b7566983a730 Mon Sep 17 00:00:00 2001 From: Burdette Lamar Date: Tue, 14 Feb 2023 14:33:05 -0600 Subject: [PATCH] [DOC] Enhanced RDoc for request headers (#120) --- doc/net-http/included_setters.rdoc | 3 -- lib/net/http/request.rb | 53 +++++++++++++++++++++++++++--- lib/net/http/requests.rb | 30 ++++++++--------- 3 files changed, 64 insertions(+), 22 deletions(-) delete mode 100644 doc/net-http/included_setters.rdoc diff --git a/doc/net-http/included_setters.rdoc b/doc/net-http/included_setters.rdoc deleted file mode 100644 index 4af977ca..00000000 --- a/doc/net-http/included_setters.rdoc +++ /dev/null @@ -1,3 +0,0 @@ -This class also includes (indirectly) module Net::HTTPHeader, -which gives access to its -{methods for setting headers}[rdoc-ref:Net::HTTPHeader@Setters]. diff --git a/lib/net/http/request.rb b/lib/net/http/request.rb index f3d32edb..e900b8a1 100644 --- a/lib/net/http/request.rb +++ b/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) # => # +# req = Net::HTTP::Get.new(uri.hostname) # => # +# +# And with any of the subclasses: +# +# req = Net::HTTP::Head.new(uri) # => # +# req = Net::HTTP::Post.new(uri) # => # +# req = Net::HTTP::Put.new(uri) # => # +# # ... +# +# 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: # diff --git a/lib/net/http/requests.rb b/lib/net/http/requests.rb index 7da2d0fe..96cedcab 100644 --- a/lib/net/http/requests.rb +++ b/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: #