From 1fad1d44850c066c12ae52420cd535d0cad4316a Mon Sep 17 00:00:00 2001 From: BurdetteLamar Date: Fri, 3 Feb 2023 21:13:40 +0000 Subject: [PATCH 1/3] Enhanced RDoc for Net::HTTP --- lib/net/http.rb | 95 +++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 76 insertions(+), 19 deletions(-) diff --git a/lib/net/http.rb b/lib/net/http.rb index 0be6db93..af3c4222 100644 --- a/lib/net/http.rb +++ b/lib/net/http.rb @@ -1058,6 +1058,7 @@ def read_timeout=(sec) # EOF # headers = {'content-type': 'application/json'} # http = Net::HTTP.new(hostname) + # http.write_timeout # => 60 # http.post(_uri.path, data, headers) # # => # # http.write_timeout = 0 @@ -1068,12 +1069,21 @@ def write_timeout=(sec) @write_timeout = sec end - # Seconds to wait for 100 Continue response. If the \HTTP object does not - # receive a response in this many seconds it sends the request body. The - # default value is +nil+. + # Returns the continue-timeout value. + # See Net::HTTP.continue_timeout=. + # attr_reader :continue_timeout - # Setter for the continue_timeout attribute. + # Sets the continue-timeout value, + # which is the number of seconds to wait for an expected 100 Continue response. + # If the \HTTP object does not receive a response in this many seconds + # it sends the request body: + # + # http = Net::HTTP.new(hostname) + # http.continue_timeout # => nil + # http.continue_timeout = 2 + # http.continue_timeout # => 2 + # def continue_timeout=(sec) @socket.continue_timeout = sec if @socket @continue_timeout = sec @@ -1089,7 +1099,19 @@ def continue_timeout=(sec) # Content-Length headers. For backwards compatibility, the default is true. attr_accessor :ignore_eof - # Returns true if the \HTTP session has been started. + # Returns +true+ if the \HTTP session has been started: + # + # http = Net::HTTP.new(hostname) + # http.started? # => false + # http.start + # http.started? # => true + # http.finish # => nil + # http.started? # => false + # Net::HTTP.start(hostname) do |http| + # http.started? + # end # => true + # http.started? # => false + # def started? @started end @@ -1098,15 +1120,30 @@ def started? attr_accessor :close_on_empty_response - # Returns true if SSL/TLS is being used with \HTTP. + # Returns +true+ if +self+ uses SSL, +false+ otherwise. + # See use_ssl=. def use_ssl? @use_ssl end - # Turn on/off SSL. - # This flag must be set before starting session. - # If you change use_ssl value after session started, - # IOError is raised. + # Sets whether a new session is to use + # {Secure Socket Layer}[https://en.wikipedia.org/wiki/Transport_Layer_Security]: + # + # port # => 443 # The HTTPS port + # http = Net::HTTP.new(hostname, port) + # http.use_ssl? # => false + # http.use_ssl = true + # http.use_ssl? # => true + # http.start do |http| + # http.use_ssl? + # end # => true + # + # Raises IOError if attempting to change during a session. + # + # Raises OpenSSL::SSL::SSLError if the port is not an HTTPS port. + # + # The setting may not be changed in an active session (raises IOError). + # def use_ssl=(flag) flag = flag ? true : false if started? and @use_ssl != flag @@ -1205,7 +1242,8 @@ def use_ssl=(flag) # See OpenSSL::SSL::SSLContext#verify_hostname= attr_accessor :verify_hostname - # Returns the X.509 certificates the server presented. + # The X509 certificate chain (an array of strings) for the session's socket peer, + # or +nil+ if none. def peer_cert if not use_ssl? or not @socket return nil @@ -1213,14 +1251,26 @@ def peer_cert @socket.io.peer_cert end - # Opens a TCP connection and \HTTP session. + # Starts an \HTTP session. # - # When this method is called with a block, it passes the \Net::HTTP - # object to the block, and closes the TCP connection and \HTTP session - # after the block has been executed. + # Without a block, returns +self+: # - # When called with a block, it returns the return value of the - # block; otherwise, it returns self. + # http = Net::HTTP.new(hostname) + # # => # + # http.start + # # => # + # http.started? # => true + # http.finish + # + # With a block, calls the block with +self+, + # finishes the session when the block exits, + # and returns the block's value: + # + # http.start do |http| + # http + # end + # # => # + # http.started? # => false # def start # :yield: http raise IOError, 'HTTP session already opened' if @started @@ -1356,8 +1406,15 @@ def on_connect end private :on_connect - # Finishes the \HTTP session and closes the TCP connection. - # Raises IOError if the session has not been started. + # Finishes the \HTTP session: + # + # http = Net::HTTP.new(hostname) + # http.start + # http.started? # => true + # http.finish # => nil + # http.started? # => false + # + # Raises IOError if not in a session. def finish raise IOError, 'HTTP session not yet started' unless started? do_finish From b5e25c17c46b905aecc43a6e2f1e0d5510a9a4e1 Mon Sep 17 00:00:00 2001 From: BurdetteLamar Date: Sat, 4 Feb 2023 16:17:08 +0000 Subject: [PATCH 2/3] Enhanced RDoc forr Net::HTTP --- lib/net/http.rb | 27 +++++---------------------- 1 file changed, 5 insertions(+), 22 deletions(-) diff --git a/lib/net/http.rb b/lib/net/http.rb index af3c4222..8cee48bb 100644 --- a/lib/net/http.rb +++ b/lib/net/http.rb @@ -1074,16 +1074,10 @@ def write_timeout=(sec) # attr_reader :continue_timeout - # Sets the continue-timeout value, + # Sets the continue timeout value, # which is the number of seconds to wait for an expected 100 Continue response. # If the \HTTP object does not receive a response in this many seconds - # it sends the request body: - # - # http = Net::HTTP.new(hostname) - # http.continue_timeout # => nil - # http.continue_timeout = 2 - # http.continue_timeout # => 2 - # + # it sends the request body. def continue_timeout=(sec) @socket.continue_timeout = sec if @socket @continue_timeout = sec @@ -1107,6 +1101,7 @@ def continue_timeout=(sec) # http.started? # => true # http.finish # => nil # http.started? # => false + # # Net::HTTP.start(hostname) do |http| # http.started? # end # => true @@ -1121,29 +1116,17 @@ def started? attr_accessor :close_on_empty_response # Returns +true+ if +self+ uses SSL, +false+ otherwise. - # See use_ssl=. + # See Net::HTTP#use_ssl=. def use_ssl? @use_ssl end # Sets whether a new session is to use - # {Secure Socket Layer}[https://en.wikipedia.org/wiki/Transport_Layer_Security]: - # - # port # => 443 # The HTTPS port - # http = Net::HTTP.new(hostname, port) - # http.use_ssl? # => false - # http.use_ssl = true - # http.use_ssl? # => true - # http.start do |http| - # http.use_ssl? - # end # => true + # {Transport Layer Security}[https://en.wikipedia.org/wiki/Transport_Layer_Security]: # # Raises IOError if attempting to change during a session. # # Raises OpenSSL::SSL::SSLError if the port is not an HTTPS port. - # - # The setting may not be changed in an active session (raises IOError). - # def use_ssl=(flag) flag = flag ? true : false if started? and @use_ssl != flag From e6a93656b9ca3f522a3256d7727d6e1a5f2cc872 Mon Sep 17 00:00:00 2001 From: BurdetteLamar Date: Sat, 4 Feb 2023 17:22:42 +0000 Subject: [PATCH 3/3] Enhanced RDoc forr Net::HTTP --- lib/net/http.rb | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lib/net/http.rb b/lib/net/http.rb index 8cee48bb..f2dd0ce8 100644 --- a/lib/net/http.rb +++ b/lib/net/http.rb @@ -1069,7 +1069,7 @@ def write_timeout=(sec) @write_timeout = sec end - # Returns the continue-timeout value. + # Returns the continue timeout value. # See Net::HTTP.continue_timeout=. # attr_reader :continue_timeout