From dfd060c583708ed8f5fa958231ec5562aa821c7a Mon Sep 17 00:00:00 2001 From: BurdetteLamar Date: Wed, 1 Feb 2023 21:19:13 +0000 Subject: [PATCH] Remarks on inclusions --- doc/net-http/included_getters.rdoc | 3 + doc/net-http/included_setters.rdoc | 3 + lib/net/http/requests.rb | 30 ++++++++ lib/net/http/responses.rb | 120 +++++++++++++++++++++++++++++ 4 files changed, 156 insertions(+) create mode 100644 doc/net-http/included_getters.rdoc create mode 100644 doc/net-http/included_setters.rdoc diff --git a/doc/net-http/included_getters.rdoc b/doc/net-http/included_getters.rdoc new file mode 100644 index 00000000..7ac327f4 --- /dev/null +++ b/doc/net-http/included_getters.rdoc @@ -0,0 +1,3 @@ +This class also includes (indirectly) module Net::HTTPHeader, +which gives access to its +{methods for getting headers}[rdoc-ref:Net::HTTPHeader@Getters]. diff --git a/doc/net-http/included_setters.rdoc b/doc/net-http/included_setters.rdoc new file mode 100644 index 00000000..4af977ca --- /dev/null +++ b/doc/net-http/included_setters.rdoc @@ -0,0 +1,3 @@ +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/requests.rb b/lib/net/http/requests.rb index 294b8e88..7da2d0fe 100644 --- a/lib/net/http/requests.rb +++ b/lib/net/http/requests.rb @@ -13,6 +13,8 @@ # http.request(req) # end # +# :include: doc/net-http/included_setters.rdoc +# # Properties: # # - Request body: optional. @@ -43,6 +45,8 @@ class Net::HTTP::Get < Net::HTTPRequest # http.request(req) # end # +# :include: doc/net-http/included_setters.rdoc +# # Properties: # # - Request body: optional. @@ -75,6 +79,8 @@ class Net::HTTP::Head < Net::HTTPRequest # http.request(req) # end # +# :include: doc/net-http/included_setters.rdoc +# # Properties: # # - Request body: yes. @@ -108,6 +114,8 @@ class Net::HTTP::Post < Net::HTTPRequest # http.request(req) # end # +# :include: doc/net-http/included_setters.rdoc +# # Properties: # # - Request body: yes. @@ -134,6 +142,8 @@ class Net::HTTP::Put < Net::HTTPRequest # http.request(req) # end # +# :include: doc/net-http/included_setters.rdoc +# # Properties: # # - Request body: optional. @@ -163,6 +173,8 @@ class Net::HTTP::Delete < Net::HTTPRequest # http.request(req) # end # +# :include: doc/net-http/included_setters.rdoc +# # Properties: # # - Request body: optional. @@ -192,6 +204,8 @@ class Net::HTTP::Options < Net::HTTPRequest # http.request(req) # end # +# :include: doc/net-http/included_setters.rdoc +# # Properties: # # - Request body: no. @@ -224,6 +238,8 @@ class Net::HTTP::Trace < Net::HTTPRequest # http.request(req) # end # +# :include: doc/net-http/included_setters.rdoc +# # Properties: # # - Request body: yes. @@ -257,6 +273,8 @@ class Net::HTTP::Patch < Net::HTTPRequest # http.request(req) # end # +# :include: doc/net-http/included_setters.rdoc +# # Related: # # - Net::HTTP#propfind: sends +PROPFIND+ request, returns response object. @@ -278,6 +296,8 @@ class Net::HTTP::Propfind < Net::HTTPRequest # http.request(req) # end # +# :include: doc/net-http/included_setters.rdoc +# # Related: # # - Net::HTTP#proppatch: sends +PROPPATCH+ request, returns response object. @@ -299,6 +319,8 @@ class Net::HTTP::Proppatch < Net::HTTPRequest # http.request(req) # end # +# :include: doc/net-http/included_setters.rdoc +# # Related: # # - Net::HTTP#mkcol: sends +MKCOL+ request, returns response object. @@ -320,6 +342,8 @@ class Net::HTTP::Mkcol < Net::HTTPRequest # http.request(req) # end # +# :include: doc/net-http/included_setters.rdoc +# # Related: # # - Net::HTTP#copy: sends +COPY+ request, returns response object. @@ -341,6 +365,8 @@ class Net::HTTP::Copy < Net::HTTPRequest # http.request(req) # end # +# :include: doc/net-http/included_setters.rdoc +# # Related: # # - Net::HTTP#move: sends +MOVE+ request, returns response object. @@ -362,6 +388,8 @@ class Net::HTTP::Move < Net::HTTPRequest # http.request(req) # end # +# :include: doc/net-http/included_setters.rdoc +# # Related: # # - Net::HTTP#lock: sends +LOCK+ request, returns response object. @@ -383,6 +411,8 @@ class Net::HTTP::Lock < Net::HTTPRequest # http.request(req) # end # +# :include: doc/net-http/included_setters.rdoc +# # Related: # # - Net::HTTP#unlock: sends +UNLOCK+ request, returns response object. diff --git a/lib/net/http/responses.rb b/lib/net/http/responses.rb index 6967f6af..6f6fb8d0 100644 --- a/lib/net/http/responses.rb +++ b/lib/net/http/responses.rb @@ -85,6 +85,8 @@ class HTTPServerError < HTTPResponse # # A +Continue+ response indicates that the server has received the request headers. # + # :include: doc/net-http/included_getters.rdoc + # # References: # # - {Mozilla}[https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/100]. @@ -100,6 +102,8 @@ class HTTPContinue < HTTPInformation # The Switching Protocol response indicates that the server has received # a request to switch protocols, and has agreed to do so. # + # :include: doc/net-http/included_getters.rdoc + # # References: # # - {Mozilla}[https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/101]. @@ -115,6 +119,8 @@ class HTTPSwitchProtocol < HTTPInformation # The +Processing+ response indicates that the server has received # and is processing the request, but no response is available yet. # + # :include: doc/net-http/included_getters.rdoc + # # References: # # - {RFC 2518}[https://www.rfc-editor.org/rfc/rfc2518#section-10.1]. @@ -130,6 +136,8 @@ class HTTPProcessing < HTTPInformation # and is processing the request, and contains certain headers; # the final response is not available yet. # + # :include: doc/net-http/included_getters.rdoc + # # References: # # - {Mozilla}[https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/103]. @@ -145,6 +153,8 @@ class HTTPEarlyHints < HTTPInformation # The +OK+ response indicates that the server has received # a request and has responded successfully. # + # :include: doc/net-http/included_getters.rdoc + # # References: # # - {Mozilla}[https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200]. @@ -160,6 +170,8 @@ class HTTPOK < HTTPSuccess # The +Created+ response indicates that the server has received # and has fulfilled a request to create a new resource. # + # :include: doc/net-http/included_getters.rdoc + # # References: # # - {Mozilla}[https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/201]. @@ -175,6 +187,8 @@ class HTTPCreated < HTTPSuccess # The +Accepted+ response indicates that the server has received # and is processing a request, but the processing has not yet been completed. # + # :include: doc/net-http/included_getters.rdoc + # # References: # # - {Mozilla}[https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/202]. @@ -192,6 +206,8 @@ class HTTPAccepted < HTTPSuccess # that received a 200 OK response from its origin, # and is returning a modified version of the origin's response. # + # :include: doc/net-http/included_getters.rdoc + # # References: # # - {Mozilla}[https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/203]. @@ -207,6 +223,8 @@ class HTTPNonAuthoritativeInformation < HTTPSuccess # The No Content response indicates that the server # successfully processed the request, and is not returning any content. # + # :include: doc/net-http/included_getters.rdoc + # # References: # # - {Mozilla}[https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/204]. @@ -223,6 +241,8 @@ class HTTPNoContent < HTTPSuccess # successfully processed the request, # asks that the client reset its document view, and is not returning any content. # + # :include: doc/net-http/included_getters.rdoc + # # References: # # - {Mozilla}[https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/205]. @@ -239,6 +259,8 @@ class HTTPResetContent < HTTPSuccess # only part of the resource (byte serving) # due to a Range header in the request. # + # :include: doc/net-http/included_getters.rdoc + # # References: # # - {Mozilla}[https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/206]. @@ -255,6 +277,8 @@ class HTTPPartialContent < HTTPSuccess # has received the request, # and that the message body can contain a number of separate response codes. # + # :include: doc/net-http/included_getters.rdoc + # # References: # # - {RFC 4818}[https://www.rfc-editor.org/rfc/rfc4918#section-11.1]. @@ -272,6 +296,8 @@ class HTTPMultiStatus < HTTPSuccess # in a preceding part of the (multi-status) response, # and are not being included again. # + # :include: doc/net-http/included_getters.rdoc + # # References: # # - {RFC 5842}[https://www.rfc-editor.org/rfc/rfc5842.html#section-7.1]. @@ -287,6 +313,8 @@ class HTTPAlreadyReported < HTTPSuccess # for the resource, and the response is a representation of the result # of one or more instance-manipulations applied to the current instance. # + # :include: doc/net-http/included_getters.rdoc + # # References: # # - {RFC 3229}[https://www.rfc-editor.org/rfc/rfc3229.html#section-10.4.1]. @@ -301,6 +329,8 @@ class HTTPIMUsed < HTTPSuccess # The Multiple Choices response indicates that the server # offers multiple options for the resource from which the client may choose. # + # :include: doc/net-http/included_getters.rdoc + # # References: # # - {Mozilla}[https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/300]. @@ -317,6 +347,8 @@ class HTTPMultipleChoices < HTTPRedirection # The Moved Permanently response indicates that links or records # returning this response should be updated to use the given URL. # + # :include: doc/net-http/included_getters.rdoc + # # References: # # - {Mozilla}[https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/301]. @@ -332,6 +364,8 @@ class HTTPMovedPermanently < HTTPRedirection # The Found response indicates that the client # should look at (browse to) another URL. # + # :include: doc/net-http/included_getters.rdoc + # # References: # # - {Mozilla}[https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/302]. @@ -347,6 +381,8 @@ class HTTPFound < HTTPRedirection # # The response to the request can be found under another URI using the GET method. # + # :include: doc/net-http/included_getters.rdoc + # # References: # # - {Mozilla}[https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/303]. @@ -362,6 +398,8 @@ class HTTPSeeOther < HTTPRedirection # Indicates that the resource has not been modified since the version # specified by the request headers. # + # :include: doc/net-http/included_getters.rdoc + # # References: # # - {Mozilla}[https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/304]. @@ -377,6 +415,8 @@ class HTTPNotModified < HTTPRedirection # The requested resource is available only through a proxy, # whose address is provided in the response. # + # :include: doc/net-http/included_getters.rdoc + # # References: # # - {RFC 9110}[https://www.rfc-editor.org/rfc/rfc9110.html#name-305-use-proxy]. @@ -391,6 +431,8 @@ class HTTPUseProxy < HTTPRedirection # The request should be repeated with another URI; # however, future requests should still use the original URI. # + # :include: doc/net-http/included_getters.rdoc + # # References: # # - {Mozilla}[https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/307]. @@ -405,6 +447,8 @@ class HTTPTemporaryRedirect < HTTPRedirection # # This and all future requests should be directed to the given URI. # + # :include: doc/net-http/included_getters.rdoc + # # References: # # - {Mozilla}[https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/308]. @@ -419,6 +463,8 @@ class HTTPPermanentRedirect < HTTPRedirection # # The server cannot or will not process the request due to an apparent client error. # + # :include: doc/net-http/included_getters.rdoc + # # References: # # - {Mozilla}[https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400]. @@ -433,6 +479,8 @@ class HTTPBadRequest < HTTPClientError # # Authentication is required, but either was not provided or failed. # + # :include: doc/net-http/included_getters.rdoc + # # References: # # - {Mozilla}[https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401]. @@ -447,6 +495,8 @@ class HTTPUnauthorized < HTTPClientError # # Reserved for future use. # + # :include: doc/net-http/included_getters.rdoc + # # References: # # - {Mozilla}[https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/402]. @@ -462,6 +512,8 @@ class HTTPPaymentRequired < HTTPClientError # The request contained valid data and was understood by the server, # but the server is refusing action. # + # :include: doc/net-http/included_getters.rdoc + # # References: # # - {Mozilla}[https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/403]. @@ -476,6 +528,8 @@ class HTTPForbidden < HTTPClientError # # The requested resource could not be found but may be available in the future. # + # :include: doc/net-http/included_getters.rdoc + # # References: # # - {Mozilla}[https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404]. @@ -490,6 +544,8 @@ class HTTPNotFound < HTTPClientError # # The request method is not supported for the requested resource. # + # :include: doc/net-http/included_getters.rdoc + # # References: # # - {Mozilla}[https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/405]. @@ -505,6 +561,8 @@ class HTTPMethodNotAllowed < HTTPClientError # The requested resource is capable of generating only content # that not acceptable according to the Accept headers sent in the request. # + # :include: doc/net-http/included_getters.rdoc + # # References: # # - {Mozilla}[https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/406]. @@ -519,6 +577,8 @@ class HTTPNotAcceptable < HTTPClientError # # The client must first authenticate itself with the proxy. # + # :include: doc/net-http/included_getters.rdoc + # # References: # # - {Mozilla}[https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/407]. @@ -533,6 +593,8 @@ class HTTPProxyAuthenticationRequired < HTTPClientError # # The server timed out waiting for the request. # + # :include: doc/net-http/included_getters.rdoc + # # References: # # - {Mozilla}[https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/408]. @@ -548,6 +610,8 @@ class HTTPRequestTimeout < HTTPClientError # # The request could not be processed because of conflict in the current state of the resource. # + # :include: doc/net-http/included_getters.rdoc + # # References: # # - {Mozilla}[https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/409]. @@ -563,6 +627,8 @@ class HTTPConflict < HTTPClientError # The resource requested was previously in use but is no longer available # and will not be available again. # + # :include: doc/net-http/included_getters.rdoc + # # References: # # - {Mozilla}[https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/410]. @@ -578,6 +644,8 @@ class HTTPGone < HTTPClientError # The request did not specify the length of its content, # which is required by the requested resource. # + # :include: doc/net-http/included_getters.rdoc + # # References: # # - {Mozilla}[https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/411]. @@ -593,6 +661,8 @@ class HTTPLengthRequired < HTTPClientError # The server does not meet one of the preconditions # specified in the request headers. # + # :include: doc/net-http/included_getters.rdoc + # # References: # # - {Mozilla}[https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/412]. @@ -607,6 +677,8 @@ class HTTPPreconditionFailed < HTTPClientError # # The request is larger than the server is willing or able to process. # + # :include: doc/net-http/included_getters.rdoc + # # References: # # - {Mozilla}[https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/413]. @@ -622,6 +694,8 @@ class HTTPPayloadTooLarge < HTTPClientError # # The URI provided was too long for the server to process. # + # :include: doc/net-http/included_getters.rdoc + # # References: # # - {Mozilla}[https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/414]. @@ -638,6 +712,8 @@ class HTTPURITooLong < HTTPClientError # # The request entity has a media type which the server or resource does not support. # + # :include: doc/net-http/included_getters.rdoc + # # References: # # - {Mozilla}[https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/415]. @@ -652,6 +728,8 @@ class HTTPUnsupportedMediaType < HTTPClientError # # The request entity has a media type which the server or resource does not support. # + # :include: doc/net-http/included_getters.rdoc + # # References: # # - {Mozilla}[https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/416]. @@ -667,6 +745,8 @@ class HTTPRangeNotSatisfiable < HTTPClientError # # The server cannot meet the requirements of the Expect request-header field. # + # :include: doc/net-http/included_getters.rdoc + # # References: # # - {Mozilla}[https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/417]. @@ -686,6 +766,8 @@ class HTTPExpectationFailed < HTTPClientError # # The request was directed at a server that is not able to produce a response. # + # :include: doc/net-http/included_getters.rdoc + # # References: # # - {RFC 9110}[https://www.rfc-editor.org/rfc/rfc9110.html#name-421-misdirected-request]. @@ -699,6 +781,8 @@ class HTTPMisdirectedRequest < HTTPClientError # # The request was well-formed but had semantic errors. # + # :include: doc/net-http/included_getters.rdoc + # # References: # # - {Mozilla}[https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422]. @@ -713,6 +797,8 @@ class HTTPUnprocessableEntity < HTTPClientError # # The requested resource is locked. # + # :include: doc/net-http/included_getters.rdoc + # # References: # # - {RFC 4918}[https://www.rfc-editor.org/rfc/rfc4918#section-11.3]. @@ -727,6 +813,8 @@ class HTTPLocked < HTTPClientError # The request failed because it depended on another request and that request failed. # See {424 Failed Dependency (WebDAV)}[https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#424]. # + # :include: doc/net-http/included_getters.rdoc + # # References: # # - {RFC 4918}[https://www.rfc-editor.org/rfc/rfc4918#section-11.4]. @@ -743,6 +831,8 @@ class HTTPFailedDependency < HTTPClientError # # The client should switch to the protocol given in the Upgrade header field. # + # :include: doc/net-http/included_getters.rdoc + # # References: # # - {Mozilla}[https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/426]. @@ -757,6 +847,8 @@ class HTTPUpgradeRequired < HTTPClientError # # The origin server requires the request to be conditional. # + # :include: doc/net-http/included_getters.rdoc + # # References: # # - {Mozilla}[https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/428]. @@ -771,6 +863,8 @@ class HTTPPreconditionRequired < HTTPClientError # # The user has sent too many requests in a given amount of time. # + # :include: doc/net-http/included_getters.rdoc + # # References: # # - {Mozilla}[https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429]. @@ -786,6 +880,8 @@ class HTTPTooManyRequests < HTTPClientError # An individual header field is too large, # or all the header fields collectively, are too large. # + # :include: doc/net-http/included_getters.rdoc + # # References: # # - {Mozilla}[https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/431]. @@ -801,6 +897,8 @@ class HTTPRequestHeaderFieldsTooLarge < HTTPClientError # 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. # + # :include: doc/net-http/included_getters.rdoc + # # References: # # - {Mozilla}[https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/451]. @@ -819,6 +917,8 @@ class HTTPUnavailableForLegalReasons < HTTPClientError # # An unexpected condition was encountered and no more specific message is suitable. # + # :include: doc/net-http/included_getters.rdoc + # # References: # # - {Mozilla}[https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500]. @@ -834,6 +934,8 @@ class HTTPInternalServerError < HTTPServerError # The server either does not recognize the request method, # or it lacks the ability to fulfil the request. # + # :include: doc/net-http/included_getters.rdoc + # # References: # # - {Mozilla}[https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/501]. @@ -849,6 +951,8 @@ class HTTPNotImplemented < HTTPServerError # The server was acting as a gateway or proxy # and received an invalid response from the upstream server. # + # :include: doc/net-http/included_getters.rdoc + # # References: # # - {Mozilla}[https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/502]. @@ -864,6 +968,8 @@ class HTTPBadGateway < HTTPServerError # The server cannot handle the request # (because it is overloaded or down for maintenance). # + # :include: doc/net-http/included_getters.rdoc + # # References: # # - {Mozilla}[https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/503]. @@ -879,6 +985,8 @@ class HTTPServiceUnavailable < HTTPServerError # The server was acting as a gateway or proxy # and did not receive a timely response from the upstream server. # + # :include: doc/net-http/included_getters.rdoc + # # References: # # - {Mozilla}[https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/504]. @@ -894,6 +1002,8 @@ class HTTPGatewayTimeout < HTTPServerError # # The server does not support the HTTP version used in the request. # + # :include: doc/net-http/included_getters.rdoc + # # References: # # - {Mozilla}[https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/505]. @@ -908,6 +1018,8 @@ class HTTPVersionNotSupported < HTTPServerError # # Transparent content negotiation for the request results in a circular reference. # + # :include: doc/net-http/included_getters.rdoc + # # References: # # - {Mozilla}[https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/506]. @@ -922,6 +1034,8 @@ class HTTPVariantAlsoNegotiates < HTTPServerError # # The server is unable to store the representation needed to complete the request. # + # :include: doc/net-http/included_getters.rdoc + # # References: # # - {Mozilla}[https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/507]. @@ -936,6 +1050,8 @@ class HTTPInsufficientStorage < HTTPServerError # # The server detected an infinite loop while processing the request. # + # :include: doc/net-http/included_getters.rdoc + # # References: # # - {Mozilla}[https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/508]. @@ -951,6 +1067,8 @@ class HTTPLoopDetected < HTTPServerError # # Further extensions to the request are required for the server to fulfill it. # + # :include: doc/net-http/included_getters.rdoc + # # References: # # - {Mozilla}[https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/510]. @@ -965,6 +1083,8 @@ class HTTPNotExtended < HTTPServerError # # The client needs to authenticate to gain network access. # + # :include: doc/net-http/included_getters.rdoc + # # References: # # - {Mozilla}[https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/511].