1 files changed, 17 insertions, 8 deletions
diff --git a/lib/open-uri.rb b/lib/open-uri.rb
index de710af261..844865b13a 100644
--- a/lib/open-uri.rb
+++ b/lib/open-uri.rb
@@ -4,22 +4,25 @@ require 'stringio'
 require 'time'
 
 module URI
-  # Allows the opening of various resources including URIs.
+  # Allows the opening of various resources including URIs. Example:
   #
-  # If the first argument responds to the 'open' method, 'open' is called on
+  #   require "open-uri"
+  #   URI.open("http://example.com") { |f| f.read }
+  #
+  # If the first argument responds to the +open+ method, +open+ is called on
   # it with the rest of the arguments.
   #
   # If the first argument is a string that begins with <code>(protocol)://</code>, it is parsed by
-  # URI.parse.  If the parsed object responds to the 'open' method,
-  # 'open' is called on it with the rest of the arguments.
+  # URI.parse.  If the parsed object responds to the +open+ method,
+  # +open+ is called on it with the rest of the arguments.
   #
   # Otherwise, Kernel#open is called.
   #
   # OpenURI::OpenRead#open provides URI::HTTP#open, URI::HTTPS#open and
   # URI::FTP#open, Kernel#open.
   #
-  # We can accept URIs and strings that begin with http://, https:// and
-  # ftp://. In these cases, the opened file object is extended by OpenURI::Meta.
+  # We can accept URIs and strings that begin with <code>http://</code>, <code>https://</code> and
+  # <code>ftp://</code>. In these cases, the opened file object is extended by OpenURI::Meta.
   def self.open(name, *rest, &block)
     if name.respond_to?(:open)
       name.open(*rest, &block)
@@ -91,8 +94,10 @@ end
 
 module OpenURI
 
+  # The version string
   VERSION = "0.5.0"
 
+  # The default options
   Options = {
     :proxy => true,
     :proxy_http_basic_authentication => true,
@@ -394,24 +399,28 @@ module OpenURI
     end
   end
 
+  # Raised on HTTP session failure
   class HTTPError < StandardError
-    def initialize(message, io)
+    def initialize(message, io) # :nodoc:
       super(message)
       @io = io
     end
+    # StringIO having the received data
     attr_reader :io
   end
 
   # Raised on redirection,
   # only occurs when +redirect+ option for HTTP is +false+.
   class HTTPRedirect < HTTPError
-    def initialize(message, io, uri)
+    def initialize(message, io, uri) # :nodoc:
       super(message, io)
       @uri = uri
     end
+    # URI to redirect
     attr_reader :uri
   end
 
+  # Raised on too many redirection,
   class TooManyRedirects < HTTPError
   end