* ext/digest/digest.c, ext/digest/md5/md5init.c,

ext/digest/rmd160/rmd160init.c, ext/digest/sha1/sha1init.c,
  ext/digest/sha2/sha2init.c: Add RDoc documentation.

* ext/digest/digest.txt, ext/digest/digest.txt.ja: Removed in
  favor of embedded RDoc documentation.


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

ChangeLog

@@ -1,3 +1,12 @@
+Fri Oct 13 20:51:55 2006  Akinori MUSHA  <knu@iDaemons.org>
+
+	* ext/digest/digest.c, ext/digest/md5/md5init.c,
+	  ext/digest/rmd160/rmd160init.c, ext/digest/sha1/sha1init.c,
+	  ext/digest/sha2/sha2init.c: Add RDoc documentation.
+
+	* ext/digest/digest.txt, ext/digest/digest.txt.ja: Removed in
+	  favor of embedded RDoc documentation.
+
 Fri Oct 13 20:38:12 2006  Akinori MUSHA  <knu@iDaemons.org>
 
 	* ext/digest/bubblebabble, ext/digest/digest.c: Rip BubbleBabble

ext/digest/digest.c

@@ -19,7 +19,16 @@ static VALUE mDigest, cDigest_Base;
 static ID id_metadata, id_new, id_initialize, id_update, id_digest;
 
 /*
- * Digest::Base
+ * Document-class: Digest
+ *
+ * This module provides a framework for message digest libraries.
+ */
+
+/*
+ * Document-class: Digest::Base
+ *
+ * This class provides a common interface to message digest
+ * algorithms.
  */
 
 static algo_t *
@@ -97,6 +106,12 @@ rb_digest_base_alloc(VALUE klass)
     return obj;
 }
 
+/*
+ * call-seq:
+ *     Digest::ALGORITHM.digest(data) -> string
+ *
+ * Returns the hash value of a given string _data_.
+ */
 static VALUE
 rb_digest_base_s_digest(VALUE klass, VALUE str)
 {
@@ -122,6 +137,12 @@ rb_digest_base_s_digest(VALUE klass, VALUE str)
     return str;
 }
 
+/*
+ * call-seq:
+ *     Digest::ALGORITHM.hexdigest(data) -> string
+ *
+ * Returns the hex-encoded hash value of a given string _data_.
+ */
 static VALUE
 rb_digest_base_s_hexdigest(VALUE klass, VALUE str)
 {
@@ -154,6 +175,12 @@ rb_digest_base_copy(VALUE copy, VALUE obj)
     return copy;
 }
 
+/*
+ * call-seq:
+ *     digest_obj.reset -> digest_obj
+ *
+ * Resets the digest to the initial state and returns self.
+ */
 static VALUE
 rb_digest_base_reset(VALUE self)
 {
@@ -176,6 +203,12 @@ rb_digest_base_reset(VALUE self)
     return self;
 }
 
+/*
+ * call-seq:
+ *     digest_obj.update(data) -> digest_obj
+ *
+ * Updates the digest using a given string _data_ and returns self.
+ */
 static VALUE
 rb_digest_base_update(VALUE self, VALUE str)
 {
@@ -197,6 +230,12 @@ rb_digest_base_update(VALUE self, VALUE str)
     return self;
 }
 
+/*
+ * call-seq:
+ *     digest_obj << data -> digest_obj
+ *
+ * Alias for update().
+ */
 static VALUE
 rb_digest_base_lshift(VALUE self, VALUE str)
 {
@@ -232,6 +271,12 @@ rb_digest_base_init(int argc, VALUE *argv, VALUE self)
     return self;
 }
 
+/*
+ * call-seq:
+ *     digest_obj.digest -> string
+ *
+ * Returns the resulting hash value.
+ */
 static VALUE
 rb_digest_base_digest(VALUE self)
 {
@@ -260,12 +305,25 @@ rb_digest_base_digest(VALUE self)
     return str;
 }
 
+/*
+ * call-seq:
+ *     digest_obj.hexdigest -> string
+ *     digest_obj.to_s -> string
+ *
+ * Returns the resulting hash value in a hex-encoded form.
+ */
 static VALUE
 rb_digest_base_hexdigest(VALUE self)
 {
     return hexdigest_str_new(rb_funcall(self, id_digest, 0));
 }
 
+/*
+ * call-seq:
+ *     digest_obj.inspect -> string
+ *
+ * Creates a printable version of the digest object.
+ */
 static VALUE
 rb_digest_base_inspect(VALUE self)
 {
@@ -292,6 +350,16 @@ rb_digest_base_inspect(VALUE self)
     return str;
 }
 
+/*
+ * call-seq:
+ *     digest_obj == string -> boolean
+ *     digest_obj == another_digest_obj -> boolean
+ *
+ * If a string is given, checks whether it is equal to the hash value
+ * of the digest object.  If another instance of the same digest class
+ * is given, checks whether they have the same hash value.  Otherwise
+ * returns false.
+ */
 static VALUE
 rb_digest_base_equal(VALUE self, VALUE other)
 {
@@ -323,24 +391,6 @@ rb_digest_base_equal(VALUE self, VALUE other)
     return Qfalse;
 }
 
-/*
- * This module provides an interface to the following hash algorithms:
- *
- *   - the MD5 Message-Digest Algorithm by the RSA Data Security,
- *     Inc., described in RFC 1321
- *
- *   - the SHA-1 Secure Hash Algorithm by NIST (the US' National
- *     Institute of Standards and Technology), described in FIPS PUB
- *     180-1.
- *
- *   - the SHA-256/384/512 Secure Hash Algorithm by NIST (the US'
- *     National Institute of Standards and Technology), described in
- *     FIPS PUB 180-2.
- *
- *   - the RIPEMD-160 cryptographic hash function, designed by Hans
- *     Dobbertin, Antoon Bosselaers, and Bart Preneel.
- */
-
 void
 Init_digest(void)
 {

ext/digest/digest.txt

@@ -1,113 +0,0 @@
-.\" digest.txt -  -*- Indented-Text -*- created at: Fri May 25 08:13:50 JST 2001
-$RoughId: digest.txt,v 1.9 2001/07/13 19:46:51 knu Exp $
-$Id$
-
-** MD5(Class)
-
-A class to implement the MD5 Message-Digest Algorithm by RSA Data
-Security, Inc., described in RFC1321.
-
-Superclass: Digest::Base
-
-require 'digest/md5'
-
-** SHA1(Class)
-
-A class to implement the SHA-1 Secure Hash Algorithm by NIST (the US'
-National Institute of Standards and Technology), described in FIPS PUB
-180-1.
-
-Superclass: Digest::Base
-
-require 'digest/sha1'
-
-** SHA256(Class)
-** SHA384(Class)
-** SHA512(Class)
-
-Classes to implement the SHA-256/384/512 Secure Hash Algorithm(s) by
-NIST (the US' National Institute of Standards and Technology),
-described in FIPS PUB 180-2.
-
-Superclass: Digest::Base
-
-require 'digest/sha2'
-
-** RMD160(Class)
-
-A class to implement the RIPEMD-160 cryptographic hash function,
-designed by Hans Dobbertin, Antoon Bosselaers, and Bart Preneel.
-
-Superclass: Digest::Base
-
-require 'digest/rmd160'
-
-
-Those above classes provide a common interface as shown below.
-
-
-Class Methods:
-
-   new([str])
-
-	Creates a new digest object.  If a string argument is given,
-	it is added to the object. (see update.)
-
-   digest(str)
-
-	Immediately calculates and return the hash of the given
-	strings as a string.  Equivalent to new(str).digest.
-
-   hexdigest(str)
-
-	Immediately calculates and return the hash of the given
-	strings as a string of hexadecimal digits.  Equivalent to
-	new(str).hexdigest.
-
-Methods:
-
-   clone
-
-	Creates a copy of the digest object.
-
-   digest
-
-	Returns the hash of the added strings as a string of 16 bytes
-	for MD5, 20 bytes for SHA1 and RMD160, 32 bytes for SHA256, 48
-	bytes for SHA384, and 64 bytes for SHA512.
-
-   hexdigest
-   to_s
-
-	Returns the hash of the added strings as a string of 32
-	hexadecimal digits for MD5, 40 hexadecimal digits for SHA1 and
-	RMD160, 64 hexadecimal digits for SHA256, 96 hexadecimal
-	digits for SHA384, and 128 hexadecimal digits for SHA512.
-	This method is equal to:
-
-	def hexdigest
-	  digest.unpack("H*")[0]
-	end
-
-   update(str)
-   << str
-
-	Appends the string str to the digest object.  Repeated calls
-	are equivalent to a single call with the concatenation of all
-	the arguments, i.e. m.update(a); m.update(b) is equivalent to
-	m.update(a + b) and m << a << b is equivalent to m << a + b.
-
-   == md
-
-	Checks if the object is equal to the given digest object.
-
-   == str
-
-	Regards the value as either a digest value or a hexdigest
-	value (depending on the length) and checks if the object is
-	equal to the given string.
-
--------------------------------------------------------
-Local variables:
-fill-column: 70
-end:

ext/digest/digest.txt.ja

@@ -1,111 +0,0 @@
-.\" digest.txt.ja -  -*- Indented-Text -*- created at: Fri May 25 08:22:19 JST 2001
-$RoughId: digest.txt.jp,v 1.8 2001/07/13 15:38:27 knu Exp $
-$Id$
-
-** MD5(クラス)
-
-RFC1321に記述されているRSA Data Security, Inc. の MD5 Message-Digest
-Algorithmを実装するクラス。
-
-Superclass: Digest::Base
-
-require 'digest/md5'
-
-** SHA1(クラス)
-
-FIPS PUB 180-1に記述されているNIST (the US' National Institute of
-Standards and Technology) の SHA-1 Secure Hash Algorithmを実装するクラス。
-
-Superclass: Digest::Base
-
-require 'digest/sha1'
-
-** SHA256(クラス)
-** SHA384(クラス)
-** SHA512(クラス)
-
-FIPS PUB 180-2に記述されているNIST (the US' National Institute of
-Standards and Technology) の SHA-256/384/512 Secure Hash Algorithmを
-実装するクラス。
-
-Superclass: Digest::Base
-
-require 'digest/sha2'
-
-** RMD160(クラス)
-
-Hans Dobbertin, Antoon Bosselaers, Bart Preneel によって設計された 
-RIPEMD-160 ハッシュ関数を実装するクラス。
-
-Superclass: Digest::Base
-
-require 'digest/rmd160'
-
-
-これらのクラスは以下のような共通のインターフェースを提供する。
-
-
-Class Methods:
-
-   new([str])
-
-        新しいダイジェストオブジェクトを生成する．文字列引数が与えられる
-        とそれを追加する(see update)。
-
-   digest(str)
-
-	与えられた文字列に対するハッシュ値を文字列で返す。
-	new(str).digest と等価。
-
-   hexdigest(str)
-
-	与えられた文字列に対するハッシュ値を、ASCIIコードを使って
-        16進数の列を示す文字列にエンコードして返す。
-	new(str).hexdigest と等価。
-
-Methods:
-
-   clone
-
-	ダイジェストオブジェクトの複製を作る。
-
-   digest
-
-        今までに追加した文字列に対するハッシュ値を文字列で返す。MD5では
-        16バイト長、SHA1およびRMD160では20バイト長、SHA256では32バイト長、
-	SHA384では48バイト長、SHA512では64バイト長となる。
-
-   hexdigest
-   to_s
-
-        今までに追加した文字列に対するハッシュ値を、ASCIIコードを使って
-        16進数の列を示す文字列にエンコードして返す。MD5では32バイト長、
-        SHA1およびRMD160では40バイト長、SHA256では64バイト長、SHA384では
-	96バイト長、SHA512では128バイト長となる。Rubyで書くと以下と同じ。
-
-	def hexdigest
-	  digest.unpack("H*")[0]
-	end
-
-   update(str)
-   << str
-
-        文字列を追加する。複数回updateを呼ぶことは文字列を連結して
-	updateを呼ぶことと等しい。すなわち m.update(a); m.update(b) は
-	m.update(a + b) と、 m << a << b は m << a + b とそれぞれ等価
-	である。
-
-   == md
-
-	与えられたダイジェストオブジェクトと比較する。
-
-   == str
-
-	与えられた文字列を digest 値、もしくは hexdigest 値と比較する。
-	いずれの値と見るかは与えられた文字列の長さによって自動判別
-	される。
-
--------------------------------------------------------
-Local variables:
-fill-column: 70
-end:

ext/digest/md5/md5init.c

@@ -16,6 +16,11 @@ static algo_t md5 = {
     (hash_finish_func_t)MD5_Finish,
 };
 
+/*
+ * A class for calculating message digests using the MD5
+ * Message-Digest Algorithm by RSA Data Security, Inc., described in
+ * RFC1321.
+ */
 void
 Init_md5()
 {

ext/digest/rmd160/rmd160init.c

@@ -16,6 +16,11 @@ static algo_t rmd160 = {
     (hash_finish_func_t)RMD160_Finish,
 };
 
+/*
+ * A class for calculating message digests using RIPEMD-160
+ * cryptographic hash function, designed by Hans Dobbertin, Antoon
+ * Bosselaers, and Bart Preneel.
+ */
 void
 Init_rmd160()
 {

ext/digest/sha1/sha1init.c

@@ -16,6 +16,11 @@ static algo_t sha1 = {
     (hash_finish_func_t)SHA1_Finish,
 };
 
+/*
+ * A class for calculating message digests using the SHA-1 Secure Hash
+ * Algorithm by NIST (the US' National Institute of Standards and
+ * Technology), described in FIPS PUB 180-1.
+ */
 void
 Init_sha1()
 {

ext/digest/sha2/sha2init.c

@@ -17,6 +17,11 @@ static algo_t sha##bitlen = { \
 
 FOREACH_BITLEN(DEFINE_ALGO_METADATA)
 
+/*
+ * Classes for calculating message digests using the SHA-256/384/512
+ * Secure Hash Algorithm(s) by NIST (the US' National Institute of
+ * Standards and Technology), described in FIPS PUB 180-2.
+ */
 void
 Init_sha2()
 {