* ext/digest: Improve documentation of Digest, Digest::HMAC and

Digest::SHA2.  Patch by Pete Higgins.  [Ruby 1.9 - Bug #4702]


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

ChangeLog

@@ -1,3 +1,8 @@
+Tue May 17 05:52:30 2011  Eric Hodel  <drbrain@segment7.net>
+
+	* ext/digest: Improve documentation of Digest, Digest::HMAC and
+	  Digest::SHA2.  Patch by Pete Higgins.  [Ruby 1.9 - Bug #4702]
+
 Tue May 17 03:51:42 2011  Eric Hodel  <drbrain@segment7.net>
 
 	* lib/abbrev.rb:  Hide copyright and revision information from RDoc.

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'
@@ -23,8 +23,8 @@ module Digest
   class ::Digest::Class
     # creates a digest object and reads a given file, _name_.
     #
-    #  p Digest::SHA256.file("X11R6.8.2-src.tar.bz2").hexdigest
-    #  # => "f02e3c85572dc9ad7cb77c2a638e3be24cc1b5bea9fdbb0b0299c9668475c534"
+    #   p Digest::SHA256.file("X11R6.8.2-src.tar.bz2").hexdigest
+    #   # => "f02e3c85572dc9ad7cb77c2a638e3be24cc1b5bea9fdbb0b0299c9668475c534"
     def self.file(name)
       new.file(name)
     end
@@ -53,8 +53,8 @@ module Digest
     # If none is given, returns the resulting hash value of the digest
     # in a base64 encoded form, keeping the digest's state.
     #
-    # If a _string_ is given, returns the hash value for the given
-    # _string_ in a base64 encoded form, resetting the digest to the
+    # If a +string+ is given, returns the hash value for the given
+    # +string+ in a base64 encoded form, resetting the digest to the
     # initial state before and after the process.
     #
     # In either case, the return value is properly padded with '=' and
@@ -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

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,38 @@ warn "use of the experimetal library 'digest/hmac' is discouraged; require 'open
 require 'digest'
 
 module Digest
+  # = digest/hmac.rb
+  #
+  # An experimental 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
+
+    # Creates a Digest::HMAC instance.
+
     def initialize(key, digester)
       @md = digester.new
 
@@ -70,23 +70,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:
+    #   hmac.update(string) -> hmac
+    #   hmac << string -> hmac
+    #
+    # Updates the hmac using a given +string+ and returns self.
     def update(text)
       @md.update(text)
       self
     end
     alias << update
 
+    # call-seq:
+    #   hmac.reset -> hmac
+    #
+    # Resets the hmac 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 +103,26 @@ module Digest
     end
     private :finish
 
+    # call-seq:
+    #   hmac.digest_length -> Integer
+    #
+    # Returns the length in bytes of the hash value of the digest.
     def digest_length
       @md.digest_length
     end
 
+    # call-seq:
+    #   hmac.block_length -> Integer
+    #
+    # Returns the block length in bytes of the hmac.
     def block_length
       @md.block_length
     end
 
+    # call-seq:
+    #   hmac.inspect -> string
+    #
+    # Creates a printable version of the hmac object.
     def inspect
       sprintf('#<%s: key=%s, digest=%s>', self.class.name, @key.inspect, @md.inspect.sub(/^\#<(.*)>$/) { $1 });
     end

ext/digest/sha2/lib/sha2.rb

@@ -18,9 +18,11 @@ module Digest
   #
   class SHA2 < Digest::Class
     # call-seq:
-    #     Digest::SHA2.new(bitlen = 256) -> digest_obj
+    #   Digest::SHA2.new(bitlen = 256) -> digest_obj
     #
     # Creates a new SHA2 hash object with a given bit length.
+    #
+    # Valid bit lengths are 256, 384 and 512.
     def initialize(bitlen = 256)
       case bitlen
       when 256
@@ -35,39 +37,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
+    #
+    # For example, 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