From 3c7d5ccdce5707d7964f01f974db505d5add590f Mon Sep 17 00:00:00 2001 From: Burdette Lamar Date: Tue, 14 Feb 2023 14:33:05 -0600 Subject: [ruby/net-http] [DOC] Enhanced RDoc for request headers (https://github.com/ruby/net-http/pull/120) https://github.com/ruby/net-http/commit/b4eb8a7932 --- lib/net/http/request.rb | 53 ++++++++++++++++++++++++++++++++++++++++++++---- lib/net/http/requests.rb | 30 +++++++++++++-------------- 2 files changed, 64 insertions(+), 19 deletions(-) (limited to 'lib/net') diff --git a/lib/net/http/request.rb b/lib/net/http/request.rb index f3d32edb62..e900b8a17a 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 7da2d0fee7..96cedcabcc 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 @@ end # 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 @@ end # 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 @@ end # 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 @@ end # 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 @@ end # 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 @@ end # 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 @@ end # 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 @@ end # 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 @@ end # 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 @@ end # 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 @@ end # 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 @@ end # 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 @@ end # 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 @@ end # http.request(req) # end # -# :include: doc/net-http/included_setters.rdoc +# See {Request Headers}[rdoc-ref:Net::HTTPRequest@Request+Headers]. # # Related: # -- cgit v1.2.3