From dbb902fc91b8b9a298d8656830f724c767345969 Mon Sep 17 00:00:00 2001 From: BurdetteLamar Date: Wed, 16 Nov 2022 17:39:17 +0000 Subject: [PATCH] [ruby/net-http] Enhanced RDoc for Net::HTTP https://github.com/ruby/net-http/commit/4444e8cea4 --- lib/net/http.rb | 54 ++++++++-------------------------------- lib/net/http/request.rb | 5 ++-- lib/net/http/response.rb | 4 +-- 3 files changed, 15 insertions(+), 48 deletions(-) diff --git a/lib/net/http.rb b/lib/net/http.rb index 535ca10a0e..7fd6f9d1b3 100644 --- a/lib/net/http.rb +++ b/lib/net/http.rb @@ -106,7 +106,7 @@ module Net #:nodoc: # Many code examples here use these example websites: # # - https://jsonplaceholder.typicode.com. - # - http:example.com. + # - http://example.com. # # Some examples also assume these variables: # @@ -137,7 +137,7 @@ module Net #:nodoc: # It consists of some or all of: scheme, hostname, path, query, and fragment; # see {URI syntax}[https://en.wikipedia.org/wiki/Uniform_Resource_Identifier#Syntax]. # - # A Ruby {URI::Generic}[]https://docs.ruby-lang.org/en/master/URI/Generic.html] object + # A Ruby {URI::Generic}[rdoc-ref:URI::Generic] object # represents an internet URI. # It provides, among others, methods # +scheme+, +hostname+, +path+, +query+, and +fragment+. @@ -204,30 +204,6 @@ module Net #:nodoc: # {Request Fields}[https://en.wikipedia.org/wiki/List_of_HTTP_header_fields#Request_fields]. # A host may also accept other custom fields. # - # The following example performs a conditional GET using the - # If-Modified-Since header: - # - # - If the file +cached_response+ has been modified since the time - # put into the header, - # the return is a \Net::HTTPSuccess object, - # and the file is overwritten with the response body. - # - Otherwise, the return is a \Net::HTTPNotModified object, - # and the file remains unchanged. - # - # The code: - # - # path = 'cached_response' - # File.write(path, '') unless File.exist?(path) - # file = File.stat(path) - # req = Net::HTTP::Get.new(uri) - # req['If-Modified-Since'] = file.mtime.rfc2822 - # res = Net::HTTP.start(hostname) do |http| - # http.request(req) - # end - # if res.is_a?(Net::HTTPSuccess) - # File.write(path, res.body) - # end - # # == Sessions # # A _session_ is a connection between a server (host) and a client that: @@ -465,7 +441,7 @@ module Net #:nodoc: # :call-seq: # Net::HTTP.get_print(hostname, path, port = 80) -> nil - # Net::HTTP:get_print(uri, headers = {}, port = 80) -> nil + # Net::HTTP:get_print(uri, headers = {}, port = uri.port) -> nil # # Like Net::HTTP.get, but writes the returned body to $stdout; # returns +nil+. @@ -480,7 +456,7 @@ module Net #:nodoc: # :call-seq: # Net::HTTP.get(hostname, path, port = 80) -> body - # Net::HTTP:get(uri, headers = {}, port = 80) -> body + # Net::HTTP:get(uri, headers = {}, port = uri.port) -> body # # Sends a GET request and returns the \HTTP response body as a string. # @@ -496,33 +472,22 @@ module Net #:nodoc: # "userId": 1, # "id": 1, # "title": "delectus aut autem", - # "completed": + # "completed": false # } # # With URI object +uri+ and optional hash argument +headers+: # # uri = URI('https://jsonplaceholder.typicode.com/todos/1') - # headers = {Accept: 'text/html'} - # puts Net::HTTP.get(uri, headers) + # headers = {'Content-type' => 'application/json; charset=UTF-8'} + # Net::HTTP.get(uri, headers) # - # Output: - # - # { - # "userId": 1, - # "id": 1, - # "title": "delectus aut autem", - # "completed": false - # } - # - # In either case, the third argument is an integer port number, - # which defaults to 80. def HTTP.get(uri_or_host, path_or_headers = nil, port = nil) get_response(uri_or_host, path_or_headers, port).body end # :call-seq: # Net::HTTP.get_response(hostname, path, port = 80) -> http_response - # Net::HTTP:get_response(uri, headers = {}, port = 80) -> http_response + # Net::HTTP:get_response(uri, headers = {}, port = uri.port) -> http_response # # Like Net::HTTP.get, but returns an Net::HTTPResponse object # instead of the body string. @@ -611,6 +576,9 @@ module Net #:nodoc: BufferedIO end + # :call-seq: + # HTTP.start(address, port, p_addr, p_port, p_user, p_pass) {|http| ... } + # HTTP.start(address, port=nil, p_addr=:ENV, p_port=nil, p_user=nil, p_pass=nil, opt) {|http| ... } # Creates a new \Net::HTTP object, # opens a TCP connection and \HTTP session. # diff --git a/lib/net/http/request.rb b/lib/net/http/request.rb index 55099019d6..1a6e588495 100644 --- a/lib/net/http/request.rb +++ b/lib/net/http/request.rb @@ -16,7 +16,7 @@ # Many code examples here use these example websites: # # - https://jsonplaceholder.typicode.com. -# - http:example.com. +# - http://example.com. # # Some examples also assume these variables: # @@ -54,8 +54,7 @@ # # A POST request may be sent using request class \Net::HTTP::Post: # -# require 'json' -# json = JSON.generate({title: 'foo', body: 'bar', userId: 1}) +# json = {title: 'foo', body: 'bar', userId: 1} # # => "{\"title\":\"foo\",\"body\":\"bar\",\"userId\":1}" # _uri = uri.dup # _uri.path = '/posts' diff --git a/lib/net/http/response.rb b/lib/net/http/response.rb index 043672d3e2..567b9573fa 100644 --- a/lib/net/http/response.rb +++ b/lib/net/http/response.rb @@ -12,7 +12,7 @@ # Many code examples here use these example websites: # # - https://jsonplaceholder.typicode.com. -# - http:example.com. +# - http://example.com. # # Some examples also assume these variables: # @@ -94,7 +94,7 @@ # - Net::HTTPAlreadyReported (208) # - Net::HTTPIMUsed (226) # -# - HTTPRedirection: +# - Net::HTTPRedirection: # # - Net::HTTPMultipleChoices (300) # - Net::HTTPMovedPermanently (301)