diff --git a/ext/digest/lib/digest.rb b/ext/digest/lib/digest.rb
index b46cf9e..1475a98 100644
--- a/ext/digest/lib/digest.rb
+++ b/ext/digest/lib/digest.rb
@@ -1,7 +1,7 @@
 require 'digest.so'
 
 module Digest
-  def self.const_missing(name)
+  def self.const_missing(name) # :nodoc:
     case name
     when :SHA256, :SHA384, :SHA512
       lib = 'digest/sha2.so'
@@ -71,6 +71,18 @@ module Digest
   end
 end
 
+# call-seq:
+#     Digest(name) -> digest_subclass
+#
+# Returns a Digest subclass by +name+.
+#
+#     require 'digest'
+#     
+#     Digest("MD5")
+#     # => Digest::MD5
+#
+#     Digest("Foo")
+#     # LoadError: library not found for class Digest::Foo -- digest/foo
 def Digest(name)
   Digest.const_get(name)
 end
diff --git a/ext/digest/lib/digest/hmac.rb b/ext/digest/lib/digest/hmac.rb
index 98f98a6..6ce1352 100644
--- a/ext/digest/lib/digest/hmac.rb
+++ b/ext/digest/lib/digest/hmac.rb
@@ -1,34 +1,3 @@
-# = digest/hmac.rb
-#
-# An implementation of HMAC keyed-hashing algorithm
-#
-# == Overview
-#
-# CAUTION: Use of this library is discouraged, because this
-# implementation was meant to be experimental but somehow got into the
-# 1.9 series without being noticed.  Please use OpenSSL::HMAC in the
-# "openssl" library instead.
-#
-# This library adds a method named hmac() to Digest classes, which
-# creates a Digest class for calculating HMAC digests.
-#
-# == Examples
-#
-#   require 'digest/hmac'
-#
-#   # one-liner example
-#   puts Digest::HMAC.hexdigest("data", "hash key", Digest::SHA1)
-#
-#   # rather longer one
-#   hmac = Digest::HMAC.new("foo", Digest::RMD160)
-#
-#   buf = ""
-#   while stream.read(16384, buf)
-#     hmac.update(buf)
-#   end
-#
-#   puts hmac.bubblebabble
-#
 # == License
 #
 # Copyright (c) 2006 Akinori MUSHA <knu@iDaemons.org>
@@ -46,7 +15,40 @@ warn "use of the experimetal library 'digest/hmac' is discouraged; require 'open
 require 'digest'
 
 module Digest
+  # = digest/hmac.rb
+  #
+  # An implementation of HMAC keyed-hashing algorithm
+  #
+  # == Overview
+  #
+  # CAUTION: Use of this library is discouraged, because this
+  # implementation was meant to be experimental but somehow got into the
+  # 1.9 series without being noticed.  Please use OpenSSL::HMAC in the
+  # "openssl" library instead.
+  #
+  # == Examples
+  #
+  #   require 'digest/hmac'
+  #
+  #   # one-liner example
+  #   puts Digest::HMAC.hexdigest("data", "hash key", Digest::SHA1)
+  #
+  #   # rather longer one
+  #   hmac = Digest::HMAC.new("foo", Digest::RMD160)
+  #
+  #   buf = ""
+  #   while stream.read(16384, buf)
+  #     hmac.update(buf)
+  #   end
+  #
+  #   puts hmac.bubblebabble
+  #
   class HMAC < Digest::Class
+    # call-seq:
+    #     digest_obj.new -> another_digest_obj
+    #
+    # Returns a new, initialized copy of the digest object.  Equivalent
+    # to digest_obj.clone().reset().
     def initialize(key, digester)
       @md = digester.new
 
@@ -70,23 +72,32 @@ module Digest
       @md.update(@ipad)
     end
 
-    def initialize_copy(other)
+    def initialize_copy(other) # :nodoc:
       @md = other.instance_eval { @md.clone }
     end
 
+    # call-seq:
+    #     digest_obj.update(string) -> digest_obj
+    #     digest_obj << string -> digest_obj
+    #
+    # Updates the digest using a given _string_ and returns self.
     def update(text)
       @md.update(text)
       self
     end
     alias << update
 
+    # call-seq:
+    #     digest_obj.reset -> digest_obj
+    #
+    # Resets the digest to the initial state and returns self.
     def reset
       @md.reset
       @md.update(@ipad)
       self
     end
 
-    def finish
+    def finish # :nodoc:
       d = @md.digest!
       @md.update(@opad)
       @md.update(d)
@@ -94,14 +105,26 @@ module Digest
     end
     private :finish
 
+    # call-seq: 
+    #     digest_obj.digest_length -> integer
+    #
+    # Returns the length of the hash value of the digest.
     def digest_length
       @md.digest_length
     end
 
+    # call-seq:
+    #     digest_obj.block_length -> integer
+    #
+    # Returns the block length of the digest.
     def block_length
       @md.block_length
     end
 
+    # call-seq:
+    #     digest_obj.inspect -> string
+    #
+    # Creates a printable version of the digest object.
     def inspect
       sprintf('#<%s: key=%s, digest=%s>', self.class.name, @key.inspect, @md.inspect.sub(/^\#<(.*)>$/) { $1 });
     end
diff --git a/ext/digest/sha2/lib/sha2.rb b/ext/digest/sha2/lib/sha2.rb
index b8e4609..277dbaa 100644
--- a/ext/digest/sha2/lib/sha2.rb
+++ b/ext/digest/sha2/lib/sha2.rb
@@ -35,39 +35,70 @@ module Digest
       @bitlen = bitlen
     end
 
-    # :nodoc:
+    # call-seq:
+    #     digest_obj.reset -> digest_obj
+    #
+    # Resets the digest to the initial state and returns self.
     def reset
       @sha2.reset
       self
     end
 
-    # :nodoc:
+    # call-seq:
+    #     digest_obj.update(string) -> digest_obj
+    #     digest_obj << string -> digest_obj
+    #
+    # Updates the digest using a given _string_ and returns self.
     def update(str)
       @sha2.update(str)
       self
     end
     alias << update
 
-    def finish
+    def finish # :nodoc:
       @sha2.digest!
     end
     private :finish
 
+
+    # call-seq:
+    #     digest_obj.block_length -> integer
+    #
+    # Returns the block length of the digest in bytes.
+    #
+    #     Digest::SHA256.new.digest_length * 8
+    #     # => 512
+    #     Digest::SHA384.new.digest_length * 8
+    #     # => 1024 
+    #     Digest::SHA512.new.digest_length * 8
+    #     # => 1024
     def block_length
       @sha2.block_length
     end
 
+    # call-seq:
+    #     digest_obj.digest_length -> integer
+    #
+    # Returns the length of the hash value of the digest in bytes.
+    #
+    #     Digest::SHA256.new.digest_length * 8
+    #     # => 256 
+    #     Digest::SHA384.new.digest_length * 8
+    #     # => 384 
+    #     Digest::SHA512.new.digest_length * 8
+    #     # => 512
+    #
+    # This means that, for example, the digests produced by Digest::SHA256 will
+    # always be 32 bytes (256 bits) in size.
     def digest_length
       @sha2.digest_length
     end
 
-    # :nodoc:
-    def initialize_copy(other)
+    def initialize_copy(other) # :nodoc:
       @sha2 = other.instance_eval { @sha2.clone }
     end
 
-    # :nodoc:
-    def inspect
+    def inspect # :nodoc:
       "#<%s:%d %s>" % [self.class.name, @bitlen, hexdigest]
     end
   end