Skip to content

Commit

Permalink
Browse files Browse the repository at this point in the history
* 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
  • Loading branch information
nurse committed Nov 27, 2010
1 parent cf869bc commit baf7a09
Show file tree
Hide file tree
Showing 2 changed files with 65 additions and 66 deletions.
5 changes: 5 additions & 0 deletions ChangeLog
@@ -1,3 +1,8 @@
Sun Nov 28 03:58:47 2010 NARUSE, Yui <naruse@ruby-lang.org>

* lib/net/http.rb: improve rdoc.
patched by Mike Perham [ruby-core:33433]

Sat Nov 27 19:12:10 2010 Tanaka Akira <akr@fsij.org>

* time.c: parenthesize macro arguments.
Expand Down
126 changes: 60 additions & 66 deletions lib/net/http.rb
Expand Up @@ -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'
Expand All @@ -36,48 +30,61 @@ class HTTPBadResponse < StandardError; end
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
Expand All @@ -97,11 +104,11 @@ class HTTPHeaderSyntaxError < StandardError; end
# 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
Expand All @@ -116,9 +123,8 @@ class HTTPHeaderSyntaxError < StandardError; end
#
# === 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'
#
Expand All @@ -130,11 +136,11 @@ class HTTPHeaderSyntaxError < StandardError; end
# :
# }
#
# 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)
#
Expand All @@ -153,8 +159,8 @@ class HTTPHeaderSyntaxError < StandardError; end
# :
# }
#
# 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
#
Expand All @@ -176,21 +182,9 @@ class HTTPHeaderSyntaxError < StandardError; end
#
# 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
#
Expand Down Expand Up @@ -280,7 +274,7 @@ class HTTPHeaderSyntaxError < StandardError; end
# 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

Expand Down Expand Up @@ -1798,7 +1792,7 @@ def initialize(path, initheader = nil)

class HTTP # reopen
#
# HTTP 1.1 methods --- RFC2616
# HTTP/1.1 methods --- RFC2616
#

class Get < HTTPRequest
Expand Down

2 comments on commit baf7a09

@anibali
Copy link

@anibali anibali commented on baf7a09 Dec 8, 2010

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Would it be a better idea to use "#=>" than "=>" when showing expected values in examples to prevent confusion with actual code? This is especially relevant seeing as "=>" is a valid token in Ruby and may confuse people copy/pasting to test the examples.

@radar
Copy link

@radar radar commented on baf7a09 Dec 8, 2010

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I agree with dismaldenizen, examples should have # before their expected return.

Please sign in to comment.