summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--ChangeLog9
-rw-r--r--ext/digest/digest.c88
-rw-r--r--ext/digest/digest.txt113
-rw-r--r--ext/digest/digest.txt.ja111
-rw-r--r--ext/digest/md5/md5init.c5
-rw-r--r--ext/digest/rmd160/rmd160init.c5
-rw-r--r--ext/digest/sha1/sha1init.c5
-rw-r--r--ext/digest/sha2/sha2init.c5
8 files changed, 98 insertions, 243 deletions
diff --git a/ChangeLog b/ChangeLog
index a592531965f..22dbe12cffb 100644
--- a/ChangeLog
+++ b/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
diff --git a/ext/digest/digest.c b/ext/digest/digest.c
index 8fa3c08dbfb..fa3fd3bfa19 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 5797dd18f96..00000000000
--- 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 8997d25b9d1..00000000000
--- 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 6fdf6e0a260..f48b56d02fb 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 585ba05c335..f0a750ebef7 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 e56f18bf632..60fb457bf90 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 c5a16ab4df6..7d145c18c7d 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()
{