[ruby/net-http] [DOC] Enhanced RDoc for Net::HTTP

(https://github.com/ruby/net-http/pull/122)

https://github.com/ruby/net-http/commit/06f79cda87
This commit is contained in:
Burdette Lamar 2023-02-16 15:52:02 -06:00 committed by git
parent 21f9c92c71
commit a49bc73e1f

View File

@ -1596,8 +1596,7 @@ module Net #:nodoc:
# get(path, initheader = nil) {|res| ... } # get(path, initheader = nil) {|res| ... }
# #
# Sends a GET request to the server; # Sends a GET request to the server;
# returns a Net::HTTPResponse object, # returns an instance of a subclass of Net::HTTPResponse.
# which actually will be an instance of a subclass of that class:
# #
# The request is based on the Net::HTTP::Get object # The request is based on the Net::HTTP::Get object
# created from string +path+ and initial headers hash +initheader+. # created from string +path+ and initial headers hash +initheader+.
@ -1631,57 +1630,81 @@ module Net #:nodoc:
res res
end end
# Gets only the header from +path+ on the connected-to host. # Sends a HEAD request to the server;
# +header+ is a Hash like { 'Accept' => '*/*', ... }. # returns an instance of a subclass of Net::HTTPResponse.
# #
# This method returns a Net::HTTPResponse object. # The request is based on the Net::HTTP::Head object
# created from string +path+ and initial headers hash +initheader+.
# #
# This method never raises an exception. # res = http.head('/todos/1') # => #<Net::HTTPOK 200 OK readbody=true>
# # res.body # => nil
# response = nil # res.to_hash.take(3)
# Net::HTTP.start('some.www.server', 80) {|http| # # =>
# response = http.head('/index.html') # [["date", ["Wed, 15 Feb 2023 15:25:42 GMT"]],
# } # ["content-type", ["application/json; charset=utf-8"]],
# p response['content-type'] # ["connection", ["close"]]]
# #
def head(path, initheader = nil) def head(path, initheader = nil)
request(Head.new(path, initheader)) request(Head.new(path, initheader))
end end
# Posts +data+ (must be a String) to +path+. +header+ must be a Hash # :call-seq:
# like { 'Accept' => '*/*', ... }. # post(path, data, initheader = nil) {|res| ... }
# #
# This method returns a Net::HTTPResponse object. # Sends a POST request to the server;
# returns an instance of a subclass of Net::HTTPResponse.
# #
# If called with a block, yields each fragment of the # The request is based on the Net::HTTP::Post object
# entity body in turn as a string as it is read from # created from string +path+, string +data+, and initial headers hash +initheader+.
# the socket. Note that in this case, the returned response
# object will *not* contain a (meaningful) body.
# #
# +dest+ argument is obsolete. # With a block given, calls the block with the response body:
# It still works but you must not use it.
# #
# This method never raises exception. # data = '{"userId": 1, "id": 1, "title": "delectus aut autem", "completed": false}'
# http.post('/todos', data) do |res|
# p res
# end # => #<Net::HTTPCreated 201 Created readbody=true>
# #
# response = http.post('/cgi-bin/search.rb', 'query=foo') # Output:
# #
# # using block # "{\n \"{\\\"userId\\\": 1, \\\"id\\\": 1, \\\"title\\\": \\\"delectus aut autem\\\", \\\"completed\\\": false}\": \"\",\n \"id\": 201\n}"
# File.open('result.txt', 'w') {|f|
# http.post('/cgi-bin/search.rb', 'query=foo') do |str|
# f.write str
# end
# }
# #
# You should set Content-Type: header field for POST. # With no block given, simply returns the response object:
# If no Content-Type: field given, this method uses #
# "application/x-www-form-urlencoded" by default. # http.post('/todos', data) # => #<Net::HTTPCreated 201 Created readbody=true>
#
# Related:
#
# - Net::HTTP::Post: request class for \HTTP method POST.
# - Net::HTTP.post: sends POST request, returns response body.
# #
def post(path, data, initheader = nil, dest = nil, &block) # :yield: +body_segment+ def post(path, data, initheader = nil, dest = nil, &block) # :yield: +body_segment+
send_entity(path, data, initheader, dest, Post, &block) send_entity(path, data, initheader, dest, Post, &block)
end end
# Sends a PATCH request to the +path+ and gets a response, # :call-seq:
# as an HTTPResponse object. # patch(path, data, initheader = nil) {|res| ... }
#
# Sends a PATCH request to the server;
# returns an instance of a subclass of Net::HTTPResponse.
#
# The request is based on the Net::HTTP::Patch object
# created from string +path+, string +data+, and initial headers hash +initheader+.
#
# With a block given, calls the block with the response body:
#
# data = '{"userId": 1, "id": 1, "title": "delectus aut autem", "completed": false}'
# http.patch('/todos/1', data) do |res|
# p res
# end # => #<Net::HTTPOK 200 OK readbody=true>
#
# Output:
#
# "{\n \"userId\": 1,\n \"id\": 1,\n \"title\": \"delectus aut autem\",\n \"completed\": false,\n \"{\\\"userId\\\": 1, \\\"id\\\": 1, \\\"title\\\": \\\"delectus aut autem\\\", \\\"completed\\\": false}\": \"\"\n}"
#
# With no block given, simply returns the response object:
#
# http.patch('/todos/1', data) # => #<Net::HTTPCreated 201 Created readbody=true>
#
def patch(path, data, initheader = nil, dest = nil, &block) # :yield: +body_segment+ def patch(path, data, initheader = nil, dest = nil, &block) # :yield: +body_segment+
send_entity(path, data, initheader, dest, Patch, &block) send_entity(path, data, initheader, dest, Patch, &block)
end end