[DOC] Enhanced RDoc for HTTPGenericRequest (#113)

lib/net/http/generic_request.rb

@@ -1,14 +1,18 @@
 # frozen_string_literal: false
-# HTTPGenericRequest is the parent of the Net::HTTPRequest class.
-# Do not use this directly; use a subclass of Net::HTTPRequest.
 #
-# Mixes in the Net::HTTPHeader module to provide easier access to HTTP headers.
+# \HTTPGenericRequest is the parent of the Net::HTTPRequest class.
+#
+# Do not use this directly; instead, use a subclass of Net::HTTPRequest.
+#
+# == About the Examples
+#
+# :include: doc/net-http/examples.rdoc
 #
 class Net::HTTPGenericRequest
 
   include Net::HTTPHeader
 
-  def initialize(m, reqbody, resbody, uri_or_path, initheader = nil)
+  def initialize(m, reqbody, resbody, uri_or_path, initheader = nil) # :nodoc:
     @method = m
     @request_has_body = reqbody
     @response_has_body = resbody
@@ -53,15 +57,47 @@ def initialize(m, reqbody, resbody, uri_or_path, initheader = nil)
     @body_data = nil
   end
 
+  # Returns the string method name for the request:
+  #
+  #   Net::HTTP::Get.new(uri).method  # => "GET"
+  #   Net::HTTP::Post.new(uri).method # => "POST"
+  #
   attr_reader :method
+
+  # Returns the string path for the request:
+  #
+  #   Net::HTTP::Get.new(uri).path # => "/"
+  #   Net::HTTP::Post.new('example.com').path # => "example.com"
+  #
   attr_reader :path
+
+  # Returns the URI object for the request, or +nil+ if none:
+  #
+  #   Net::HTTP::Get.new(uri).uri
+  #   # => #<URI::HTTPS https://jsonplaceholder.typicode.com/>
+  #   Net::HTTP::Get.new('example.com').uri # => nil
+  #
   attr_reader :uri
 
-  # Automatically set to false if the user sets the Accept-Encoding header.
-  # This indicates they wish to handle Content-encoding in responses
-  # themselves.
+  # Returns +false+ if the request's header <tt>'Accept-Encoding'</tt>
+  # has been set manually or deleted
+  # (indicating that the user intends to handle encoding in the response),
+  # +true+ otherwise:
+  #
+  #   req = Net::HTTP::Get.new(uri) # => #<Net::HTTP::Get GET>
+  #   req['Accept-Encoding']        # => "gzip;q=1.0,deflate;q=0.6,identity;q=0.3"
+  #   req.decode_content            # => true
+  #   req['Accept-Encoding'] = 'foo'
+  #   req.decode_content            # => false
+  #   req.delete('Accept-Encoding')
+  #   req.decode_content            # => false
+  #
   attr_reader :decode_content
 
+  # Returns a string representation of the request:
+  #
+  #   Net::HTTP::Post.new(uri).inspect # => "#<Net::HTTP::Post POST>"
+  #
   def inspect
     "\#<#{self.class} #{@method}>"
   end
@@ -76,30 +112,70 @@ def []=(key, val) # :nodoc:
     super key, val
   end
 
+  # Returns whether the request may have a body:
+  #
+  #   Net::HTTP::Post.new(uri).request_body_permitted? # => true
+  #   Net::HTTP::Get.new(uri).request_body_permitted?  # => false
+  #
   def request_body_permitted?
     @request_has_body
   end
 
+  # Returns whether the response may have a body:
+  #
+  #   Net::HTTP::Post.new(uri).response_body_permitted? # => true
+  #   Net::HTTP::Head.new(uri).response_body_permitted? # => false
+  #
   def response_body_permitted?
     @response_has_body
   end
 
-  def body_exist?
+  def body_exist? # :nodoc:
     warn "Net::HTTPRequest#body_exist? is obsolete; use response_body_permitted?", uplevel: 1 if $VERBOSE
     response_body_permitted?
   end
 
+  # Returns the string body for the request, or +nil+ if there is none:
+  #
+  #   req = Net::HTTP::Post.new(uri)
+  #   req.body # => nil
+  #   req.body = '{"title": "foo","body": "bar","userId": 1}'
+  #   req.body # => "{\"title\": \"foo\",\"body\": \"bar\",\"userId\": 1}"
+  #
   attr_reader :body
 
+  # Sets the body for the request:
+  #
+  #   req = Net::HTTP::Post.new(uri)
+  #   req.body # => nil
+  #   req.body = '{"title": "foo","body": "bar","userId": 1}'
+  #   req.body # => "{\"title\": \"foo\",\"body\": \"bar\",\"userId\": 1}"
+  #
   def body=(str)
     @body = str
     @body_stream = nil
     @body_data = nil
     str
   end
 
+  # Returns the body stream object for the request, or +nil+ if there is none:
+  #
+  #   req = Net::HTTP::Post.new(uri)          # => #<Net::HTTP::Post POST>
+  #   req.body_stream                         # => nil
+  #   require 'stringio'
+  #   req.body_stream = StringIO.new('xyzzy') # => #<StringIO:0x0000027d1e5affa8>
+  #   req.body_stream                         # => #<StringIO:0x0000027d1e5affa8>
+  #
   attr_reader :body_stream
 
+  # Sets the body stream for the request:
+  #
+  #   req = Net::HTTP::Post.new(uri)          # => #<Net::HTTP::Post POST>
+  #   req.body_stream                         # => nil
+  #   require 'stringio'
+  #   req.body_stream = StringIO.new('xyzzy') # => #<StringIO:0x0000027d1e5affa8>
+  #   req.body_stream                         # => #<StringIO:0x0000027d1e5affa8>
+  #
   def body_stream=(input)
     @body = nil
     @body_stream = input