diff --git a/lib/uri.rb b/lib/uri.rb
index 41bb09b..14ccf71 100644
--- a/lib/uri.rb
+++ b/lib/uri.rb
@@ -2,13 +2,99 @@
 # URI support for Ruby
 #
 # Author:: Akira Yamada <akira@ruby-lang.org>
-# Documentation:: Akira Yamada <akira@ruby-lang.org>, Dmitry V. Sabanin <sdmitry@lrn.ru>
+# Documentation::
+#   Akira Yamada <akira@ruby-lang.org>
+#   Dmitry V. Sabanin <sdmitry@lrn.ru>
+#   Vincent Batts <vbatts@hashbangbash.com>
 # License::
 #  Copyright (c) 2001 akira yamada <akira@ruby-lang.org>
 #  You can redistribute it and/or modify it under the same term as Ruby.
-# Revision:: $Id$
 #
-# See URI for documentation
+#
+# == Developer Documentation
+#
+# === Class tree
+#
+# - URI::Generic (in uri/generic.rb)
+#   - URI::FTP - (in uri/ftp.rb)
+#   - URI::HTTP - (in uri/http.rb)
+#     - URI::HTTPS - (in uri/https.rb)
+#   - URI::LDAP - (in uri/ldap.rb)
+#     - URI::LDAPS - (in uri/ldaps.rb)
+#   - URI::MailTo - (in uri/mailto.rb)
+# - URI::Parser - (in uri/common.rb)
+# - URI::REGEXP - (in uri/common.rb)
+#   - URI::REGEXP::PATTERN - (in uri/common.rb)
+# - URI::Util - (in uri/common.rb)
+# - URI::Escape - (in uri/common.rb)
+# - URI::Error - (in uri/common.rb)
+#   - URI::InvalidURIError - (in uri/common.rb)
+#   - URI::InvalidComponentError - (in uri/common.rb)
+#   - URI::BadURIError - (in uri/common.rb)
+#
+#
+# == URI
+#
+# === Introduction
+#
+# URI is a module providing classes to handle Uniform Resource Identifiers (RFC2396)
+#
+# === Features
+#
+# * Uniform handling of handling URIs
+# * Flexibility to introduce custom URI schemes
+# * Flexibility to have an alternate URI::Parser (or just different patterns and regexp's)
+#
+# === Basic example
+#
+#   require 'uri'
+#
+#   uri = URI("http://foo.com/posts?id=30&limit=5#time=1305298413")
+#   #=> #<URI::HTTP:0x00000000b14880 URL:http://foo.com/posts?id=30&limit=5#time=1305298413>
+#   uri.scheme
+#   #=> "http"
+#   uri.host
+#   #=> "foo.com"
+#   uri.path
+#   #=> "/posts"
+#   uri.query
+#   #=> "id=30&limit=5"
+#   uri.fragment
+#   #=> "time=1305298413"
+#
+#   uri.to_s
+#   #=> "http://foo.com/posts?id=30&limit=5#time=1305298413"
+#
+# === Next step example
+#
+#   module URI
+#     class RSYNC < Generic
+#       DEFAULT_PORT = 873
+#     end
+#     @@schemes['RSYNC'] = RSYNC
+#   end
+#   #=> URI::RSYNC
+#
+#   URI.scheme_list
+#   #=> {"FTP"=>URI::FTP, "HTTP"=>URI::HTTP, "HTTPS"=>URI::HTTPS, "LDAP"=>URI::LDAP, "LDAPS"=>URI::LDAPS, "MAILTO"=>URI::MailTo, "RSYNC"=>URI::RSYNC}
+#
+#   uri = URI("rsync://rysnc.foo.com")
+#   #=> #<URI::RSYNC:0x00000000f648c8 URL:rsync://rsync.foo.com>
+#
+# == RFC References
+#
+# A good place to view an RFC spec is http://www.ietf.org/rfc.html
+#
+# Here is a list of all related RFC's.
+# - RFC822
+# - RFC1738
+# - RFC2255
+# - RFC2368
+# - RFC2373
+# - RFC2396
+# - RFC2732
+# - RFC3986
+#
 #
 
 module URI
diff --git a/lib/uri/common.rb b/lib/uri/common.rb
index db53872..c258f5a 100644
--- a/lib/uri/common.rb
+++ b/lib/uri/common.rb
@@ -1,10 +1,12 @@
 # = uri/common.rb
 #
 # Author:: Akira Yamada <akira@ruby-lang.org>
-# Revision:: $Id$
 # License::
 #   You can redistribute it and/or modify it under the same term as Ruby.
 #
+# See URI for general documentation
+#
+#
 
 module URI
   # 
@@ -633,7 +635,7 @@ module URI
       DEFAULT_PARSER.unescape(*arg)
     end
     alias decode unescape
-  end
+  end # module Escape
 
   extend Escape
   include REGEXP
@@ -977,7 +979,7 @@ module URI
     end
     ary
   end
-end
+end # module URI
 
 module Kernel
 
diff --git a/lib/uri/ftp.rb b/lib/uri/ftp.rb
index 663ecd5..4965d01 100644
--- a/lib/uri/ftp.rb
+++ b/lib/uri/ftp.rb
@@ -1,9 +1,9 @@
-#
 # = uri/ftp.rb
 #
 # Author:: Akira Yamada <akira@ruby-lang.org>
 # License:: You can redistribute it and/or modify it under the same term as Ruby.
-# Revision:: $Id$
+#
+# See URI for general documentation
 #
 
 require 'uri/generic'
diff --git a/lib/uri/generic.rb b/lib/uri/generic.rb
index a512100..e2e1e79 100644
--- a/lib/uri/generic.rb
+++ b/lib/uri/generic.rb
@@ -1,10 +1,9 @@
-
-#
 # = uri/generic.rb
 #
 # Author:: Akira Yamada <akira@ruby-lang.org>
 # License:: You can redistribute it and/or modify it under the same term as Ruby.
-# Revision:: $Id$
+#
+# See URI for general documentation
 #
 
 require 'uri/common'
diff --git a/lib/uri/http.rb b/lib/uri/http.rb
index 7d63ff5..784e79a 100644
--- a/lib/uri/http.rb
+++ b/lib/uri/http.rb
@@ -1,9 +1,9 @@
-#
 # = uri/http.rb
 #
 # Author:: Akira Yamada <akira@ruby-lang.org>
 # License:: You can redistribute it and/or modify it under the same term as Ruby.
-# Revision:: $Id$
+#
+# See URI for general documentation
 #
 
 require 'uri/generic'
diff --git a/lib/uri/https.rb b/lib/uri/https.rb
index 767f333..e78ca2d 100644
--- a/lib/uri/https.rb
+++ b/lib/uri/https.rb
@@ -1,9 +1,9 @@
-#
 # = uri/https.rb
 #
 # Author:: Akira Yamada <akira@ruby-lang.org>
 # License:: You can redistribute it and/or modify it under the same term as Ruby.
-# Revision:: $Id$
+#
+# See URI for general documentation
 #
 
 require 'uri/http'
diff --git a/lib/uri/ldap.rb b/lib/uri/ldap.rb
index 561082a..4af2fb3 100644
--- a/lib/uri/ldap.rb
+++ b/lib/uri/ldap.rb
@@ -1,13 +1,11 @@
-#
 # = uri/ldap.rb
 #
 # Author::
 #  Takaaki Tateishi <ttate@jaist.ac.jp>
 #  Akira Yamada <akira@ruby-lang.org>
-# License::
-#   URI::LDAP is copyrighted free software by Takaaki Tateishi and Akira Yamada.
-#   You can redistribute it and/or modify it under the same term as Ruby.
-# Revision:: $Id$
+# License:: You can redistribute it and/or modify it under the same term as Ruby.
+#
+# See URI for general documentation
 #
 
 require 'uri/generic'
diff --git a/lib/uri/ldaps.rb b/lib/uri/ldaps.rb
index bfea6ce..42bbfe8 100644
--- a/lib/uri/ldaps.rb
+++ b/lib/uri/ldaps.rb
@@ -1,3 +1,10 @@
+# = uri/ldap.rb
+#
+# License:: You can redistribute it and/or modify it under the same term as Ruby.
+#
+# See URI for general documentation
+#
+
 require 'uri/ldap'
 
 module URI
diff --git a/lib/uri/mailto.rb b/lib/uri/mailto.rb
index 1e8f2da..19466e0 100644
--- a/lib/uri/mailto.rb
+++ b/lib/uri/mailto.rb
@@ -1,9 +1,9 @@
-#
 # = uri/mailto.rb
 #
 # Author:: Akira Yamada <akira@ruby-lang.org>
 # License:: You can redistribute it and/or modify it under the same term as Ruby.
-# Revision:: $Id$
+#
+# See URI for general documentation
 #
 
 require 'uri/generic'
