From 5cafaa674431aeb3bdddca88867372adbc1dbc9c Mon Sep 17 00:00:00 2001 From: knu Date: Fri, 13 Oct 2006 11:52:18 +0000 Subject: * 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 --- ext/digest/digest.c | 88 +++++++++++++++++++++++++------- ext/digest/digest.txt | 113 ----------------------------------------- ext/digest/digest.txt.ja | 111 ---------------------------------------- ext/digest/md5/md5init.c | 5 ++ ext/digest/rmd160/rmd160init.c | 5 ++ ext/digest/sha1/sha1init.c | 5 ++ ext/digest/sha2/sha2init.c | 5 ++ 7 files changed, 89 insertions(+), 243 deletions(-) delete mode 100644 ext/digest/digest.txt delete mode 100644 ext/digest/digest.txt.ja (limited to 'ext/digest') diff --git a/ext/digest/digest.c b/ext/digest/digest.c index 8fa3c08dbf..fa3fd3bfa1 100644 --- a/ext/digest/digest.c +++ b/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) { diff --git a/ext/digest/digest.txt b/ext/digest/digest.txt deleted file mode 100644 index 5797dd18f9..0000000000 --- a/ext/digest/digest.txt +++ /dev/null @@ -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: diff --git a/ext/digest/digest.txt.ja b/ext/digest/digest.txt.ja deleted file mode 100644 index 8997d25b9d..0000000000 --- a/ext/digest/digest.txt.ja +++ /dev/null @@ -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: diff --git a/ext/digest/md5/md5init.c b/ext/digest/md5/md5init.c index 6fdf6e0a26..f48b56d02f 100644 --- a/ext/digest/md5/md5init.c +++ b/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() { diff --git a/ext/digest/rmd160/rmd160init.c b/ext/digest/rmd160/rmd160init.c index 585ba05c33..f0a750ebef 100644 --- a/ext/digest/rmd160/rmd160init.c +++ b/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() { diff --git a/ext/digest/sha1/sha1init.c b/ext/digest/sha1/sha1init.c index e56f18bf63..60fb457bf9 100644 --- a/ext/digest/sha1/sha1init.c +++ b/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() { diff --git a/ext/digest/sha2/sha2init.c b/ext/digest/sha2/sha2init.c index c5a16ab4df..7d145c18c7 100644 --- a/ext/digest/sha2/sha2init.c +++ b/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() { -- cgit v1.2.3