* ext/digest/digest.c: Add documentation for Digest.

  [Feature #10452][ruby-core:66001][ci skip]
  * remove HMAC from list of digest algorithms,
  * add MD5 in list of digest algorithms,
  * add information about writing a C digest implementation using Digest::Base,
  * add documentation for Digest::Base public methods.
* ext/digest/md5/md5init.c: add examples for MD5.
* ext/digest/rmd160/rmd160init.c: add examples for Digest::RMD160.
* ext/digest/sha1/sha1init.c: add examples for Digest::SHA1.

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

1 files changed, 39 insertions, 5 deletions

diff --git a/ext/digest/sha2/lib/sha2.rb b/ext/digest/sha2/lib/sha2.rb
index 58ff9f5cf0..e5a44ff0d4 100644
--- a/ext/digest/sha2/lib/sha2.rb
+++ b/ext/digest/sha2/lib/sha2.rb
@@ -17,11 +17,45 @@ module Digest
   #
   # A meta digest provider class for SHA256, SHA384 and SHA512.
   #
+  # FIPS 180-2 describes SHA2 family of digest algorithms. It defines
+  # three algorithms:
+  # * one which works on chunks of 512 bits and returns a 256-bit
+  #   digest (SHA256),
+  # * one which works on chunks of 1024 bits and returns a 384-bit
+  #   digest (SHA384),
+  # * and one which works on chunks of 1024 bits and returns a 512-bit
+  #   digest (SHA512).
+  #
+  # ==Examples
+  #  require 'digest'
+  #  
+  #  # Compute a complete digest
+  #  Digest::SHA2.hexdigest 'abc'          # => "ba7816bf8..."
+  #  Digest::SHA2.new(256).hexdigest 'abc' # => "ba7816bf8..."
+  #  Digest::SHA256.hexdigest 'abc'        # => "ba7816bf8..."
+  #  
+  #  Digest::SHA2.new(384).hexdigest 'abc' # => "cb00753f4..."
+  #  Digest::SHA384.hexdigest 'abc'        # => "cb00753f4..."
+  #  
+  #  Digest::SHA2.new(512).hexdigest 'abc' # => "ddaf35a19..."
+  #  Digest::SHA512.hexdigest 'abc'        # => "ddaf35a19..."
+  #  
+  #  # Compute digest by chunks
+  #  sha2 = Digest::SHA2.new               # =>#<Digest::SHA2:256>
+  #  sha2.update "ab"
+  #  sha2 << "c"                           # alias for #update
+  #  sha2.hexdigest                        # => "ba7816bf8..."
+  #
+  #  # Use the same object to compute another digest
+  #  sha2.reset
+  #  sha2 << "message"
+  #  sha2.hexdigest                        # => "ab530a13e..."
+  #
   class SHA2 < Digest::Class
     # call-seq:
     #   Digest::SHA2.new(bitlen = 256) -> digest_obj
     #
-    # Creates a new SHA2 hash object with a given bit length.
+    # Create a new SHA2 hash object with a given bit length.
     #
     # Valid bit lengths are 256, 384 and 512.
     def initialize(bitlen = 256)
@@ -41,7 +75,7 @@ module Digest
     # call-seq:
     #   digest_obj.reset -> digest_obj
     #
-    # Resets the digest to the initial state and returns self.
+    # Reset the digest to the initial state and return self.
     def reset
       @sha2.reset
       self
@@ -51,7 +85,7 @@ module Digest
     #   digest_obj.update(string) -> digest_obj
     #   digest_obj << string -> digest_obj
     #
-    # Updates the digest using a given _string_ and returns self.
+    # Update the digest using a given _string_ and return self.
     def update(str)
       @sha2.update(str)
       self
@@ -67,7 +101,7 @@ module Digest
     # call-seq:
     #   digest_obj.block_length -> Integer
     #
-    # Returns the block length of the digest in bytes.
+    # Return the block length of the digest in bytes.
     #
     #   Digest::SHA256.new.block_length * 8
     #   # => 512
@@ -82,7 +116,7 @@ module Digest
     # call-seq:
     #   digest_obj.digest_length -> Integer
     #
-    # Returns the length of the hash value of the digest in bytes.
+    # Return the length of the hash value (the digest) in bytes.
     #
     #   Digest::SHA256.new.digest_length * 8
     #   # => 256