rbs 3.7.0 → 3.8.0.pre.1

data/stdlib/net-http/0/net-http.rbs

@@ -18,7 +18,6 @@ module Net
   #     overview](https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol#Techni
   #     cal_overview).
   #
-  #
   # ## About the Examples
   #
   # Examples here assume that `net/http` has been required (which also requires
@@ -31,7 +30,6 @@ module Net
   # *   https://jsonplaceholder.typicode.com.
   # *   http://example.com.
   #
-  #
   # Some examples also assume these variables:
   #
   #     uri = URI('https://jsonplaceholder.typicode.com/')
@@ -79,6 +77,8 @@ module Net
   #         Net::HTTP.post(uri, data)
   #         params = {title: 'foo', body: 'bar', userId: 1}
   #         Net::HTTP.post_form(uri, params)
+  #         data = '{"title": "foo", "body": "bar", "userId": 1}'
+  #         Net::HTTP.put(uri, data)
   #
   # *   If performance is important, consider using sessions, which lower request
   #     overhead. This [session](rdoc-ref:Net::HTTP@Sessions) has multiple
@@ -108,7 +108,6 @@ module Net
   #           # Session finished automatically at block exit.
   #         end
   #
-  #
   # The methods cited above are convenience methods that, via their few arguments,
   # allow minimal control over the requests. For greater control, consider using
   # [request objects](rdoc-ref:Net::HTTPRequest).
@@ -196,7 +195,6 @@ module Net
   # *   May contain any number of requests.
   # *   Is ended by instance method Net::HTTP#finish.
   #
-  #
   # See example sessions at [Strategies](rdoc-ref:Net::HTTP@Strategies).
   #
   # ### Session Using Net::HTTP.start
@@ -209,7 +207,6 @@ module Net
   # *   Executing the block.
   # *   Calling #finish after block execution.
   #
-  #
   # In the block, you can use these instance methods, each of which that sends a
   # single request:
   #
@@ -225,7 +222,6 @@ module Net
   #     *   #trace: TRACE.
   #     *   #patch: PATCH.
   #
-  #
   # *   [WebDAV methods](https://en.wikipedia.org/wiki/WebDAV#Implementation):
   #
   #     *   #copy: COPY.
@@ -236,8 +232,6 @@ module Net
   #     *   #proppatch: PROPPATCH.
   #     *   #unlock: UNLOCK.
   #
-  #
-  #
   # ### Session Using Net::HTTP.start and Net::HTTP.finish
   #
   # You can manage a session manually using methods #start and #finish:
@@ -259,20 +253,17 @@ module Net
   # *   Finishing the session.
   # *   Destroying the object.
   #
-  #
   # Such methods that send GET requests:
   #
   # *   ::get: Returns the string response body.
   # *   ::get_print: Writes the string response body to $stdout.
   # *   ::get_response: Returns a Net::HTTPResponse object.
   #
-  #
   # Such methods that send POST requests:
   #
   # *   ::post: Posts data to the host.
   # *   ::post_form: Posts form data to the host.
   #
-  #
   # ## HTTP Requests and Responses
   #
   # Many of the methods above are convenience methods, each of which sends a
@@ -285,7 +276,6 @@ module Net
   # *   Net::HTTPRequest.
   # *   Net::HTTPResponse.
   #
-  #
   # ## Following Redirection
   #
   # Each returned response is an instance of a subclass of Net::HTTPResponse. See
@@ -453,7 +443,6 @@ module Net
   #         http = Net::HTTP.new('example.com', nil, 'my.proxy', 8000, 'pname', 'ppass', 'my.proxy,proxy.example:8000')
   #         http.proxy_address # => nil
   #
-  #
   # ## Compression and Decompression
   #
   # Net::HTTP does not compress the body of a request before sending.
@@ -480,9 +469,12 @@ module Net
   #     header.
   # *   Any other value: leaves the body and header unchanged.
   #
-  #
   # ## What's Here
   #
+  # First, what's elsewhere. Class Net::HTTP:
+  #
+  # *   Inherits from [class Object](rdoc-ref:Object@What-27s+Here).
+  #
   # This is a categorized summary of methods and attributes.
   #
   # ### Net::HTTP Objects
@@ -491,7 +483,6 @@ module Net
   # *   [#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
@@ -502,7 +493,6 @@ module Net
   # *   [#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
@@ -530,7 +520,6 @@ module Net
   # *   [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
@@ -543,6 +532,8 @@ module Net
   #     form data and returns a response object.
   # *   [::post](rdoc-ref:Net::HTTP.post): Sends a POST request with data and
   #     returns a response object.
+  # *   [::put](rdoc-ref:Net::HTTP.put): Sends a PUT 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
@@ -590,7 +581,6 @@ module Net
   # *   [#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):
@@ -606,7 +596,6 @@ module Net
   # *   [#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
@@ -629,7 +618,6 @@ module Net
   # *   [#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
@@ -694,7 +682,6 @@ module Net
   #     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
@@ -719,7 +706,6 @@ module Net
   #     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
@@ -727,7 +713,6 @@ module Net
   #     [::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
@@ -925,7 +910,6 @@ module Net
     #     Server](rdoc-ref:Net::HTTP@Proxy+Server).
     # *   For argument `opts`, see below.
     #
-    #
     # With no block given:
     #
     # *   Calls `http.start` with no block (see #start), which opens a TCP
@@ -938,7 +922,6 @@ module Net
     #         http.finish
     #         http.started? # => false
     #
-    #
     # With a block given:
     #
     # *   Calls `http.start` with the block (see #start), which:
@@ -948,10 +931,8 @@ module Net
     #     *   Closes the HTTP session and TCP connection on block exit.
     #     *   Returns the block's value `object`.
     #
-    #
     # *   Returns `object`.
     #
-    #
     # Example:
     #
     #     hostname = 'jsonplaceholder.typicode.com'
@@ -999,7 +980,6 @@ module Net
     # *   #verify_mode
     # *   #write_timeout
     #
-    #
     # Note: If `port` is `nil` and `opts[:use_ssl]` is a truthy value, the value
     # passed to `new` is Net::HTTP.https_default_port, not `port`.
     #
@@ -1015,7 +995,7 @@ module Net
 
     # <!--
     #   rdoc-file=lib/net/http.rb
-    #   - new(address, port = nil, p_addr = :ENV, p_port = nil, p_user = nil, p_pass = nil, p_no_proxy = nil)
+    #   - new(address, port = nil, p_addr = :ENV, p_port = nil, p_user = nil, p_pass = nil, p_no_proxy = nil, p_use_ssl = nil)
     # -->
     # Returns a new Net::HTTP object `http` (but does not open a TCP connection or
     # HTTP session).
@@ -1027,7 +1007,6 @@ module Net
     # *   Has the default port number, Net::HTTP.default_port (80).
     # *   Has no proxy.
     #
-    #
     # Example:
     #
     #     http = Net::HTTP.new(hostname)
@@ -1706,6 +1685,11 @@ module Net
     #     http = Net::HTTP.new(hostname)
     #     http.put('/todos/1', data) # => #<Net::HTTPOK 200 OK readbody=true>
     #
+    # Related:
+    #
+    # *   Net::HTTP::Put: request class for HTTP method PUT.
+    # *   Net::HTTP.put: sends PUT request, returns response body.
+    #
     def put: (String path, String data, ?headers initheader) -> Net::HTTPResponse
 
     # <!--
@@ -2040,7 +2024,6 @@ module Net
   # *   https://jsonplaceholder.typicode.com.
   # *   http://example.com.
   #
-  #
   # Some examples also assume these variables:
   #
   #     uri = URI('https://jsonplaceholder.typicode.com/')
@@ -2208,7 +2191,6 @@ module Net
   # *   Net::HTTPGenericRequest (and therefore Net::HTTPRequest).
   # *   Net::HTTPResponse.
   #
-  #
   # The headers are a hash-like collection of key/value pairs called *fields*.
   #
   # ## Request and Response Fields
@@ -2223,7 +2205,6 @@ module Net
   #     [Getters](rdoc-ref:Net::HTTPHeader@Getters) and
   #     [Iterators](rdoc-ref:Net::HTTPHeader@Iterators).
   #
-  #
   # Exactly which fields should be sent or expected depends on the host; see:
   #
   # *   [Request
@@ -2233,7 +2214,6 @@ module Net
   #     fields](https://en.wikipedia.org/wiki/List_of_HTTP_header_fields#Response_
   #     fields).
   #
-  #
   # ## About the Examples
   #
   # Examples here assume that `net/http` has been required (which also requires
@@ -2246,7 +2226,6 @@ module Net
   # *   https://jsonplaceholder.typicode.com.
   # *   http://example.com.
   #
-  #
   # Some examples also assume these variables:
   #
   #     uri = URI('https://jsonplaceholder.typicode.com/')
@@ -2283,7 +2262,6 @@ module Net
   # *   A symbol: Key `:Accept` is treated as if it were `:Accept.to_s.downcase`;
   #     i.e., `'accept'`.
   #
-  #
   # Examples:
   #
   #     req = Net::HTTP::Get.new(uri)
@@ -2306,7 +2284,6 @@ module Net
   #     *   #to_hash: Returns a hash of all header fields: each key is a field
   #         name; its value is the array value for the field.
   #
-  #
   # *   These methods return field values as string; the string value for a field
   #     is equivalent to `self[key.downcase.to_s].join(', '))`:
   #
@@ -2315,8 +2292,6 @@ module Net
   #     *   #fetch: Like #[], but accepts a default value to be returned if the
   #         key does not exist.
   #
-  #
-  #
   # The field value may be set:
   #
   # *   #[]=: Sets the value for the given key; the given value may be a string, a
@@ -2325,7 +2300,6 @@ module Net
   #     overwriting the existing value).
   # *   #delete: Deletes the field for the given key.
   #
-  #
   # Example field values:
   #
   # *   String:
@@ -2362,7 +2336,6 @@ module Net
   #         req[:foo]            # => "bar, baz, bat, bam, bah, 0, bad, 1"
   #         req.get_fields(:foo) # => ["bar", "baz", "bat", "bam", "bah", "0", "bad", "1"]
   #
-  #
   # ## Convenience Methods
   #
   # Various convenience methods retrieve values, set values, query values, set
@@ -2382,13 +2355,11 @@ module Net
   #     `'Proxy-Authorization'`.
   # *   #set_range: Sets the value for field `'Range'`.
   #
-  #
   # ### Form Setters
   #
   # *   #set_form: Sets an HTML form data set.
   # *   #set_form_data: Sets header fields and a body from HTML form data.
   #
-  #
   # ### Getters
   #
   # Method #[] can retrieve the value of any field that exists, but always as a
@@ -2410,7 +2381,6 @@ module Net
   #     `'Content-Range'`.
   # *   #type_params: Returns the string parameters for `'Content-Type'`.
   #
-  #
   # ### Queries
   #
   # *   #chunked?: Returns whether field `'Transfer-Encoding'` is set to
@@ -2421,7 +2391,6 @@ module Net
   #     `'keep-alive'`.
   # *   #key?: Returns whether a given key exists.
   #
-  #
   # ### Iterators
   #
   # *   #each_capitalized: Passes each field capitalized-name/value pair to the
@@ -3039,7 +3008,6 @@ module Net
     # *   A name/value pair.
     # *   An IO stream opened for reading.
     #
-    #
     # Argument `params` should be an
     # [Enumerable](rdoc-ref:Enumerable@Enumerable+in+Ruby+Classes) (method
     # `params.map` will be called), and is often an array or hash.
@@ -3076,13 +3044,10 @@ module Net
     #         *   `:filename`: The name of the file to use.
     #         *   `:content_type`: The content type of the uploaded file.
     #
-    #
     #         Example:
     #
     #             req.set_form([['file', file, {filename: "other-filename.foo"}]]
     #
-    #
-    #
     # The various forms may be mixed:
     #
     #     req.set_form(['foo', %w[bar 1], ['file', file]])
@@ -3100,8 +3065,6 @@ module Net
     #     *   An IO stream opened for reading (only when argument `enctype` -- see
     #         below -- is given as `'multipart/form-data'`).
     #
-    #
-    #
     # Examples:
     #
     #     # Nil-valued fields.
@@ -3124,7 +3087,6 @@ module Net
     # *   `'multipart/form-data'`; see [RFC
     #     7578](https://www.rfc-editor.org/rfc/rfc7578).
     #
-    #
     # Optional argument `formopt` is a hash of options (applicable only when
     # argument `enctype` is `'multipart/form-data'`) that may include the following
     # entries:
@@ -3240,7 +3202,6 @@ module Net
   #     Host](https://en.wikipedia.org/wiki/List_of_HTTP_header_fields#host-reques
   #     t-header).
   #
-  #
   # You can add headers or override default headers:
   #
   #     #   res = Net::HTTP::Get.new(uri, {'foo' => '0', 'bar' => '1'})
@@ -3262,7 +3223,6 @@ module Net
   # *   Net::HTTP::Trace
   # *   Net::HTTP::Patch
   #
-  #
   # Subclasses for WebDAV requests:
   #
   # *   Net::HTTP::Propfind
@@ -3314,7 +3274,6 @@ module Net
   # *   [Cacheable](https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol#Cach
   #     eable_methods): yes.
   #
-  #
   # Related:
   #
   # *   Net::HTTP.get: sends `GET` request, returns response body.
@@ -3354,7 +3313,6 @@ module Net
   # *   [Cacheable](https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol#Cach
   #     eable_methods): yes.
   #
-  #
   # Related:
   #
   # *   Net::HTTP#head: sends `HEAD` request, returns response object.
@@ -3396,7 +3354,6 @@ module Net
   # *   [Cacheable](https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol#Cach
   #     eable_methods): yes.
   #
-  #
   # Related:
   #
   # *   Net::HTTP.post: sends `POST` request, returns response object.
@@ -3439,6 +3396,11 @@ module Net
   # *   [Cacheable](https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol#Cach
   #     eable_methods): no.
   #
+  # Related:
+  #
+  # *   Net::HTTP.put: sends `PUT` request, returns response object.
+  # *   Net::HTTP#put: sends `PUT` request, returns response object.
+  #
   class HTTP::Put < HTTPRequest
     METHOD: String
 
@@ -3474,7 +3436,6 @@ module Net
   # *   [Cacheable](https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol#Cach
   #     eable_methods): no.
   #
-  #
   # Related:
   #
   # *   Net::HTTP#delete: sends `DELETE` request, returns response object.
@@ -3513,7 +3474,6 @@ module Net
   # *   [Cacheable](https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol#Cach
   #     eable_methods): no.
   #
-  #
   # Related:
   #
   # *   Net::HTTP#options: sends `OPTIONS` request, returns response object.
@@ -3552,7 +3512,6 @@ module Net
   # *   [Cacheable](https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol#Cach
   #     eable_methods): no.
   #
-  #
   # Related:
   #
   # *   Net::HTTP#trace: sends `TRACE` request, returns response object.
@@ -3594,7 +3553,6 @@ module Net
   # *   [Cacheable](https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol#Cach
   #     eable_methods): no.
   #
-  #
   # Related:
   #
   # *   Net::HTTP#patch: sends `PATCH` request, returns response object.
@@ -3804,7 +3762,6 @@ module Net
   # *   https://jsonplaceholder.typicode.com.
   # *   http://example.com.
   #
-  #
   # Some examples also assume these variables:
   #
   #     uri = URI('https://jsonplaceholder.typicode.com/')
@@ -3851,7 +3808,6 @@ module Net
   # *   Hash-like method `[]`.
   # *   Specific reader methods, such as `content_type`.
   #
-  #
   # Examples:
   #
   #     res = Net::HTTP.get_response(uri) # => #<Net::HTTPOK 200 OK readbody=true>
@@ -3884,7 +3840,6 @@ module Net
   #     *   Net::HTTPProcessing (102)
   #     *   Net::HTTPEarlyHints (103)
   #
-  #
   # *   Net::HTTPSuccess:
   #
   #     *   Net::HTTPOK (200)
@@ -3898,7 +3853,6 @@ module Net
   #     *   Net::HTTPAlreadyReported (208)
   #     *   Net::HTTPIMUsed (226)
   #
-  #
   # *   Net::HTTPRedirection:
   #
   #     *   Net::HTTPMultipleChoices (300)
@@ -3910,7 +3864,6 @@ module Net
   #     *   Net::HTTPTemporaryRedirect (307)
   #     *   Net::HTTPPermanentRedirect (308)
   #
-  #
   # *   Net::HTTPClientError:
   #
   #     *   Net::HTTPBadRequest (400)
@@ -3941,7 +3894,6 @@ module Net
   #     *   Net::HTTPRequestHeaderFieldsTooLarge (431)
   #     *   Net::HTTPUnavailableForLegalReasons (451)
   #
-  #
   # *   Net::HTTPServerError:
   #
   #     *   Net::HTTPInternalServerError (500)
@@ -3956,8 +3908,6 @@ module Net
   #     *   Net::HTTPNotExtended (510)
   #     *   Net::HTTPNetworkAuthenticationRequired (511)
   #
-  #
-  #
   # There is also the Net::HTTPBadResponse exception which is raised when there is
   # a protocol error.
   #
@@ -5423,7 +5373,6 @@ module Net
   # *   https://jsonplaceholder.typicode.com.
   # *   http://example.com.
   #
-  #
   # Some examples also assume these variables:
   #
   #     uri = URI('https://jsonplaceholder.typicode.com/')
@@ -5470,7 +5419,6 @@ module Net
   # *   Hash-like method `[]`.
   # *   Specific reader methods, such as `content_type`.
   #
-  #
   # Examples:
   #
   #     res = Net::HTTP.get_response(uri) # => #<Net::HTTPOK 200 OK readbody=true>
@@ -5503,7 +5451,6 @@ module Net
   #     *   Net::HTTPProcessing (102)
   #     *   Net::HTTPEarlyHints (103)
   #
-  #
   # *   Net::HTTPSuccess:
   #
   #     *   Net::HTTPOK (200)
@@ -5517,7 +5464,6 @@ module Net
   #     *   Net::HTTPAlreadyReported (208)
   #     *   Net::HTTPIMUsed (226)
   #
-  #
   # *   Net::HTTPRedirection:
   #
   #     *   Net::HTTPMultipleChoices (300)
@@ -5529,7 +5475,6 @@ module Net
   #     *   Net::HTTPTemporaryRedirect (307)
   #     *   Net::HTTPPermanentRedirect (308)
   #
-  #
   # *   Net::HTTPClientError:
   #
   #     *   Net::HTTPBadRequest (400)
@@ -5560,7 +5505,6 @@ module Net
   #     *   Net::HTTPRequestHeaderFieldsTooLarge (431)
   #     *   Net::HTTPUnavailableForLegalReasons (451)
   #
-  #
   # *   Net::HTTPServerError:
   #
   #     *   Net::HTTPInternalServerError (500)
@@ -5575,8 +5519,6 @@ module Net
   #     *   Net::HTTPNotExtended (510)
   #     *   Net::HTTPNetworkAuthenticationRequired (511)
   #
-  #
-  #
   # There is also the Net::HTTPBadResponse exception which is raised when there is
   # a protocol error.
   #