* lib/net/http.rb: improve rdoc.

  patched by Mike Perham [ruby-core:33433]

git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@29953 b2dd03c8-39d4-4d8f-98ff-823fe69b080e

1 files changed, 60 insertions, 66 deletions

diff --git a/lib/net/http.rb b/lib/net/http.rb
index 33c88c8ce5..092a27b072 100644
--- a/lib/net/http.rb
+++ b/lib/net/http.rb
@@ -18,12 +18,6 @@
 #
 # See Net::HTTP for an overview and examples.
 #
-# NOTE: You can find Japanese version of this document here:
-# http://www.ruby-lang.org/ja/man/html/net_http.html
-#
-#--
-# $Id$
-#++
 
 require 'net/protocol'
 autoload :OpenSSL, 'openssl'
@@ -36,48 +30,61 @@ module Net   #:nodoc:
   class HTTPHeaderSyntaxError < StandardError; end
   # :startdoc:
 
-  # == What Is This Library?
+  # == An HTTP client API for Ruby.
   #
-  # This library provides your program functions to access WWW
-  # documents via HTTP, Hyper Text Transfer Protocol version 1.1.
-  # For details of HTTP, refer to [RFC2616]
-  # (http://www.ietf.org/rfc/rfc2616.txt).
+  # For more details about HTTP, see [RFC2616](http://www.ietf.org/rfc/rfc2616.txt).
   #
   # == Examples
   #
-  # === Getting Document From WWW Server
+  # === Fetching Documents
   #
-  # Example #1: Simple GET+print
+  # Simple GET
   #
   #     require 'net/http'
-  #     Net::HTTP.get_print 'www.example.com', '/index.html'
-  #
-  # Example #2: Simple GET+print by URL
-  #
-  #     require 'net/http'
-  #     require 'uri'
-  #     Net::HTTP.get_print URI.parse('http://www.example.com/index.html')
+  #     Net::HTTP.get('www.example.com', '/index.html') => String
   #
-  # Example #3: More generic GET+print
+  # Simple GET by URI object
   #
   #     require 'net/http'
   #     require 'uri'
-  #
-  #     url = URI.parse('http://www.example.com/index.html')
-  #     res = Net::HTTP.start(url.hostname, url.port) {|http|
-  #       http.get('/index.html')
-  #     }
-  #     puts res.body
-  #
-  # Example #4: More generic GET+print
-  #
-  #     require 'net/http'
-  #
-  #     url = URI.parse('http://www.example.com/index.html')
-  #     req = Net::HTTP::Get.new(url.path)
-  #     res = Net::HTTP.start(url.hostname, url.port) {|http|
-  #       http.request(req)
-  #     }
+  #     Net::HTTP.get(URI.parse('http://www.example.com/index.html?count=10')) => String
+  #
+  # More generic GET with dynamic parameters
+  #
+  #    require 'net/http'
+  #    require 'uri'
+  #
+  #    uri = URI.parse('http://www.example.com/index.html')
+  #    params = { :limit => 10, :page => 3 }
+  #    uri.query = URI.encode_www_form(params)
+  #    res = Net::HTTP.get_response(uri)
+  #    puts res.body if res.is_a?(Net::HTTPSuccess)
+  #
+  # Even more generic GET with Basic Auth and custom header
+  #
+  #    require 'net/http'
+  #
+  #    uri = URI.parse('http://www.example.com/index.html?key=value')
+  #    req = Net::HTTP::Get.new(uri.request_uri)
+  #    req.basic_auth 'user', 'pass'
+  #    req['X-Custom-Header'] = Time.now.to_i
+  #    res = Net::HTTP.start(uri.hostname, uri.port) {|http|
+  #      http.request(req)
+  #    }
+  #    puts res.body
+  #
+  # Accessing Response data:
+  #
+  #     res = Net::HTTP.get_response(URI.parse('http://www.example.com/index.html'))
+  #     # Headers
+  #     res['Set-Cookie']            => String
+  #     res.get_fields('set-cookie') => Array
+  #     res.to_hash['set-cookie']    => Array
+  #     puts "Headers: #{res.to_hash.inspect}"
+  #     # Status
+  #     puts res.code => '200'
+  #     puts res.message => 'OK'
+  #     puts res.class.name => 'HTTPOK'
   #     puts res.body
   #
   # === Posting Form Data
@@ -97,11 +104,11 @@ module Net   #:nodoc:
   #     puts res.body
   #
   #     #3: Detailed control
-  #     url = URI.parse('http://www.example.com/todo.cgi')
-  #     req = Net::HTTP::Post.new(url.path)
+  #     uri = URI.parse('http://www.example.com/todo.cgi')
+  #     req = Net::HTTP::Post.new(uri.path)
   #     req.basic_auth 'jack', 'pass'
   #     req.set_form_data({'from' => '2005-01-01', 'to' => '2005-03-31'}, ';')
-  #     res = Net::HTTP.new(url.hostname, url.port).start {|http| http.request(req) }
+  #     res = Net::HTTP.new(uri.hostname, uri.port).start {|http| http.request(req) }
   #     case res
   #     when Net::HTTPSuccess, Net::HTTPRedirection
   #       # OK
@@ -116,9 +123,8 @@ module Net   #:nodoc:
   #
   # === Accessing via Proxy
   #
-  # Net::HTTP.Proxy creates http proxy class. It has same
-  # methods of Net::HTTP but its instances always connect to
-  # proxy, instead of given host.
+  # Net::HTTP::Proxy has the same methods as Net::HTTP but its instances always
+  # connect via the proxy, instead of given host.
   #
   #     require 'net/http'
   #
@@ -130,11 +136,11 @@ module Net   #:nodoc:
   #             :
   #     }
   #
-  # Since Net::HTTP.Proxy returns Net::HTTP itself when proxy_addr is nil,
-  # there's no need to change code if there's proxy or not.
+  # Since Net::HTTP::Proxy returns Net::HTTP itself when proxy_addr is nil,
+  # there's no need to change code if there's a proxy or not.
   #
-  # There are two additional parameters in Net::HTTP.Proxy which allow to
-  # specify proxy user name and password:
+  # There are two additional parameters in Net::HTTP::Proxy which you can use to
+  # specify a proxy username and password:
   #
   #     Net::HTTP::Proxy(proxy_addr, proxy_port, proxy_user = nil, proxy_pass = nil)
   #
@@ -153,8 +159,8 @@ module Net   #:nodoc:
   #             :
   #     }
   #
-  # Note that net/http never rely on HTTP_PROXY environment variable.
-  # If you want to use proxy, set it explicitly.
+  # Note that net/http does not use the HTTP_PROXY environment variable.
+  # If you want to use a proxy, you must set it explicitly.
   #
   # === Following Redirection
   #
@@ -176,21 +182,9 @@ module Net   #:nodoc:
   #
   #     print fetch('http://www.ruby-lang.org')
   #
-  # Net::HTTPSuccess and Net::HTTPRedirection is a HTTPResponse class.
-  # All HTTPResponse objects belong to its own response class which
-  # indicate HTTP result status. For details of response classes,
-  # see section "HTTP Response Classes".
-  #
-  # === Basic Authentication
-  #
-  #     require 'net/http'
-  #
-  #     Net::HTTP.start('www.example.com') {|http|
-  #       req = Net::HTTP::Get.new('/secret-page.html')
-  #       req.basic_auth 'account', 'password'
-  #       response = http.request(req)
-  #       print response.body
-  #     }
+  # Net::HTTPSuccess and Net::HTTPRedirection are HTTPResponse subclasses.
+  # All HTTPResponse objects belong to their own response class which
+  # indicates the HTTP result status.
   #
   # === HTTP Request Classes
   #
@@ -280,7 +274,7 @@ module Net   #:nodoc:
   #     Net::HTTP.version_1_2
   #     Net::HTTP.start {|http3| ...(http3 has 1.2 features)... }
   #
-  # This function is NOT thread-safe.
+  # Switching versions is NOT thread-safe.
   #
   class HTTP < Protocol
 
@@ -1798,7 +1792,7 @@ module Net   #:nodoc:
 
   class HTTP   # reopen
     #
-    # HTTP 1.1 methods --- RFC2616
+    # HTTP/1.1 methods --- RFC2616
     #
 
     class Get < HTTPRequest