update documents, comments

5 files changed, 210 insertions, 132 deletions

diff --git a/fml/lib/Mail/ThreadTrack.pm b/fml/lib/Mail/ThreadTrack.pm
index 5e7f1ab7..59680d6b 100755
--- a/fml/lib/Mail/ThreadTrack.pm
+++ b/fml/lib/Mail/ThreadTrack.pm
@@ -4,7 +4,7 @@
 #   All rights reserved. This program is free software; you can
 #   redistribute it and/or modify it under the same terms as Perl itself.
 #
-# $FML: ThreadTrack.pm,v 1.22 2001/11/26 09:12:38 fukachan Exp $
+# $FML: ThreadTrack.pm,v 1.23 2001/12/22 09:21:15 fukachan Exp $
 #
 
 package Mail::ThreadTrack;
@@ -68,9 +68,9 @@ C<$id> is sequential number for input data (article).
 
 
 # Descriptions: constructor
-#    Arguments: $self
+#    Arguments: OBJ($self)
 # Side Effects: none
-# Return Value: object
+# Return Value: OBJ
 sub new
 {
     my ($self, $args) = @_;
@@ -143,9 +143,9 @@ sub DESTROY {}
 
 
 # Descriptions: "mkdir -p" or "mkdirhier"
-#    Arguments: directory [file_mode]
+#    Arguments: STR($dir) STR($mode)
 # Side Effects: set $ErrorString
-# Return Value: succeeded to create directory or not
+# Return Value: 1 or UNDEF
 sub _mkdirhier
 {
     my ($dir, $mode) = @_;
@@ -163,7 +163,7 @@ sub _mkdirhier
 
 # Descriptions: set up directory which is taken from
 #               $self->{ _db_dir }
-#    Arguments: $self $curproc $args
+#    Arguments: OBJ($self) HASH_REF($args)
 # Side Effects: create a "_db_dir" directory if needed
 # Return Value: 1 (success) or undef (fail)
 sub _init_dir
@@ -195,9 +195,9 @@ and save its new number to C<file>.
 
 
 # Descriptions: increment thread number $id holded in $seq_file
-#    Arguments: $self $seq_file
+#    Arguments: OBJ($self) STR($seq_file)
 # Side Effects: increment id holded in $seq_file
-# Return Value: number
+# Return Value: NUM
 sub increment_id
 {
     my ($self, $seq_file) = @_;
@@ -230,9 +230,9 @@ return @thread_id ARRAY
 
 
 # Descriptions: return @thread_id ARRAY
-#    Arguments: $self $args
-# Side Effects:
-# Return Value: none
+#    Arguments: OBJ($self) HASH_REF($args)
+# Side Effects: update statistics
+# Return Value: ARRAY_HASH
 sub list_up_thread_id
 {
     my ($self) = @_;
@@ -278,9 +278,9 @@ get output format.
 
 
 # Descriptions: set output format
-#    Arguments: $self $string
+#    Arguments: OBJ($self) STR($mode)
 # Side Effects: none
-# Return Value: string
+# Return Value: STR
 sub set_mode
 {
     my ($self, $mode) = @_;
@@ -289,9 +289,9 @@ sub set_mode
 
 
 # Descriptions: set output format
-#    Arguments: $self
+#    Arguments: OBJ($self)
 # Side Effects: none
-# Return Value: string
+# Return Value: STR
 sub get_mode
 {
     my ($self) = @_;
@@ -301,11 +301,15 @@ sub get_mode
 
 =head2 set_fd( $fd )
 
-=head2 get_fd( $fd )
+=head2 get_fd()
 
 =cut
 
 
+# Descriptions: set output format
+#    Arguments: OBJ($self) HADNLE($fd)
+# Side Effects: none
+# Return Value: STR
 sub set_fd
 {
     my ($self, $fd) = @_;
@@ -314,9 +318,9 @@ sub set_fd
 
 
 # Descriptions: set output format
-#    Arguments: $self $string
+#    Arguments: OBJ($self)
 # Side Effects: none
-# Return Value: string
+# Return Value: STR
 sub get_fd
 {
     my ($self) = @_;
@@ -331,6 +335,10 @@ set thread listing order where $order is 'normal' or 'reverse'.
 =cut
 
 
+# Descriptions: set thread listing order
+#    Arguments: OBJ($self) STR($order)
+# Side Effects: none
+# Return Value: none
 sub set_order
 {
     my ($self, $order) = @_;
@@ -349,13 +357,15 @@ sub set_order
 
 =head2 exist($thread_id)
 
+$thread_id exists or not?
+
 =cut
 
 
-# Descriptions:
-#    Arguments: $self $string
-# Side Effects:
-# Return Value: none
+# Descriptions: $thread_id exists or not?
+#    Arguments: OBJ($self) STR($id)
+# Side Effects: none
+# Return Value: 1 or 0
 sub exist
 {
     my ($self, $id) = @_;
@@ -383,6 +393,10 @@ close specified $thread_id.
 =cut
 
 
+# Descriptions: close specified $thread_id.
+#    Arguments: OBJ($self) STR($thread_id)
+# Side Effects: update status
+# Return Value: none
 sub close
 {
     my ($self, $thread_id) = @_;
@@ -408,9 +422,9 @@ C<set_status()> calls db_open() an db_close() automatically within it.
 =cut
 
 
-# Descriptions:
-#    Arguments: $self $curproc $args
-# Side Effects:
+# Descriptions: set status
+#    Arguments: OBJ($self) HASH_REF($args)
+# Side Effects: update status
 # Return Value: none
 sub set_status
 {
@@ -424,9 +438,9 @@ sub set_status
 }
 
 
-# Descriptions:
-#    Arguments: $self $args
-# Side Effects:
+# Descriptions: set status
+#    Arguments: OBJ($self) HASH_REF($args)
+# Side Effects: update status
 # Return Value: none
 sub _set_status
 {
@@ -445,6 +459,10 @@ add filter rule to ignore in thread database.
 =cut
 
 
+# Descriptions: add filter rule to ignore in thread database.
+#    Arguments: OBJ($self) HASH_REF($hash)
+# Side Effects: none
+# Return Value: none
 sub add_filter
 {
     my ($self, $hash) = @_;
@@ -459,11 +477,14 @@ sub add_filter
 
 =head2 log( $str )
 
+log $str
+
 =cut
 
-# Descriptions:
-#    Arguments: $self $args
-# Side Effects:
+
+# Descriptions: log
+#    Arguments: OBJ($self) STR($str)
+# Side Effects: none
 # Return Value: none
 sub log
 {
diff --git a/fml/lib/Mail/ThreadTrack/Analyze.pm b/fml/lib/Mail/ThreadTrack/Analyze.pm
index e1bd6de2..54ee9de2 100644
--- a/fml/lib/Mail/ThreadTrack/Analyze.pm
+++ b/fml/lib/Mail/ThreadTrack/Analyze.pm
@@ -4,7 +4,7 @@
 #   All rights reserved. This program is free software; you can
 #   redistribute it and/or modify it under the same terms as Perl itself.
 #
-# $FML: Analyze.pm,v 1.19 2001/12/21 07:34:05 tmu Exp $
+# $FML: Analyze.pm,v 1.20 2001/12/22 09:21:20 fukachan Exp $
 #
 
 package Mail::ThreadTrack::Analyze;
@@ -42,7 +42,7 @@ This is top level entrance for
 
 
 # Descriptions: top level entrance
-#    Arguments: $self $msg
+#    Arguments: OBJ($self) STR($msg)
 #               $msg = "Mail::Messge object"
 # Side Effects: none
 # Return Value: none
@@ -65,9 +65,9 @@ analyze message given by $msg and assign thread id if needed.
 
 
 # Descriptions: given string looks like subject or not
-#    Arguments: $string
+#    Arguments: STR($subject)
 # Side Effects: none
-# Return Value: 1/0
+# Return Value: 1 or 0
 sub _is_reply
 {
     my ($subject) = @_;
@@ -79,7 +79,7 @@ sub _is_reply
 
 # Descriptions: assign a new thread id or
 #               extract the existing thread-id from the subject
-#    Arguments: $self $msg
+#    Arguments: OBJ($self) OBJ($msg)
 #                  $msg = Mail::Message object
 # Side Effects: a new thread_id may be assigned
 # Return Value: none
@@ -144,10 +144,10 @@ sub assign
 }
 
 
-# Descriptions:
-#    Arguments: $self
-# Side Effects:
-# Return Value: number
+# Descriptions: assign new thread_id
+#    Arguments: OBJ($self)
+# Side Effects: increment id
+# Return Value: NUM
 sub _assign_new_thread_id_number
 {
     my ($self) = @_;
@@ -169,9 +169,9 @@ sub _assign_new_thread_id_number
 
 
 # Descriptions: update $self->{ _status_info }
-#    Arguments: $self $str
+#    Arguments: OBJ($self) STR($s)
 # Side Effects: update $self->{ _status_info }
-# Return Value: none
+# Return Value: STR
 sub _append_thread_status_info
 {
     my ($self, $s) = @_;
@@ -181,15 +181,19 @@ sub _append_thread_status_info
 
 =head2 get_thread_status()
 
+get thread status
+
 =head2 set_thread_status($status)
 
+set thread status
+
 =cut
 
 
-# Descriptions:
-#    Arguments: $self $args
-# Side Effects:
-# Return Value: none
+# Descriptions: get thread status
+#    Arguments: OBJ($self)
+# Side Effects: none
+# Return Value: STR
 sub get_thread_status
 {
     my ($self) = @_;
@@ -197,10 +201,10 @@ sub get_thread_status
 }
 
 
-# Descriptions:
-#    Arguments: $self $args
-# Side Effects:
-# Return Value: none
+# Descriptions: set thread status
+#    Arguments: OBJ($self) STR($thread_status)
+# Side Effects: none
+# Return Value: STR
 sub set_thread_status
 {
     my ($self, $thread_status) = @_;
@@ -214,9 +218,9 @@ sub set_thread_status
 =cut
 
 
-# Descriptions:
-#    Arguments: $self $args
-# Side Effects:
+# Descriptions: update thread status
+#    Arguments: OBJ($self) OBJ($msg)
+# Side Effects: update database
 # Return Value: none
 sub update_thread_status
 {
@@ -260,6 +264,10 @@ sub update_thread_status
 }
 
 
+# Descriptions: check filter whether this $msg should be ignored or not.
+#    Arguments: OBJ($self) OBJ($msg)
+# Side Effects: none
+# Return Value: 1 or 0
 sub _is_ignore
 {
     my ($self, $msg) = @_;
@@ -293,10 +301,10 @@ sub _is_ignore
 =cut
 
 
-# Descriptions:
-#    Arguments: $self $args
-# Side Effects:
-# Return Value: none
+# Descriptions: get thread_id
+#    Arguments: OBJ($self)
+# Side Effects: none
+# Return Value: STR or UNDEF
 sub get_thread_id
 {
     my ($self) = @_;
@@ -304,10 +312,10 @@ sub get_thread_id
 }
 
 
-# Descriptions:
-#    Arguments: $self $args
-# Side Effects:
-# Return Value: none
+# Descriptions: set thread_id
+#    Arguments: OBJ($self) STR($thread_id)
+# Side Effects: none
+# Return Value: STR
 sub set_thread_id
 {
     my ($self, $thread_id) = @_;
@@ -318,10 +326,10 @@ sub set_thread_id
 
 # Descriptions: create regexp for a subject tag, for example
 #               "[%s %05d]" => "\[\S+ \d+\]"
-#    Arguments: a subject tag string
+#    Arguments: STR($s)
 #               XXX non OO type function
 # Side Effects: none
-# Return Value: a regexp for the given tag
+# Return Value: STR(a regexp for the given tag)
 sub _regexp_compile
 {
     my ($s) = @_;
@@ -343,10 +351,10 @@ sub _regexp_compile
 
 
 # Descriptions: extract message-id list and return it.
-#    Arguments: $header
+#    Arguments: OBJ($header)
 #               function not OO
 # Side Effects: none
-# Return Value: HASH ARRAY
+# Return Value: ARRAY_HASH
 sub _extract_message_id_references
 {
     my ($header) = @_;
@@ -377,10 +385,10 @@ sub _extract_message_id_references
 }
 
 
-# Descriptions:
-#    Arguments: $self $args
-# Side Effects:
-# Return Value: none
+# Descriptions: extract thread_id in Subject:
+#    Arguments: OBJ($self) OBJ($header)
+# Side Effects: none
+# Return Value: STR or 0
 sub _extract_thread_id_in_subject
 {
     my ($self, $header) = @_;
@@ -413,22 +421,29 @@ sub _extract_thread_id_in_subject
 }
 
 
-# For example, consider a posting to both elena ML and rudo (DM) from kenken.
+# Descriptions: 
+#               For example, consider a posting to both elena ML and 
+#               rudo (DM) from kenken.
 #
-#     From: kenken
-#     To: elena-ml
-#     Cc: rudo
+#                    From: kenken
+#                    To: elena-ml
+#                    Cc: rudo
 #
-# The reply to this DM (direct message) from rudo is
+#                The reply to this DM (direct message) from rudo is
 #
-#     From: rudo
-#     To: elena-ml
+#                    From: rudo
+#                    To: elena-ml
 #
-# This reply message has no thread_id since the message from kenken to
-# rudo comes directly from kenken not through fml driver.
-# In this case, we try to speculdate the reply relation and the thread_id
-# of this thread by using _speculate_thread_id_from_header().
+#                    This reply message has no thread_id since the
+#                    message from kenken to rudo comes directly from
+#                    kenken not through fml driver.  In this case, we
+#                    try to speculdate the reply relation and the
+#                    thread_id of this thread by using _
+#                    speculate_thread_id_from_header().
 #
+#    Arguments: OBJ($self) OBJ($header)
+# Side Effects: none
+# Return Value: STR(message id)
 sub _speculate_thread_id_from_header
 {
     my ($self, $header) = @_;
@@ -455,10 +470,10 @@ sub _speculate_thread_id_from_header
 }
 
 
-# Descriptions:
-#    Arguments: $self $id_num
+# Descriptions: create thread_id
+#    Arguments: OBJ($self) STR($id)
 # Side Effects: update $self->{ _thread_subject_tag }
-# Return Value: thread_id string
+# Return Value: STR(thread_id string)
 sub _create_thread_id_strings
 {
     my ($self, $id) = @_;
@@ -479,9 +494,9 @@ sub _create_thread_id_strings
 =cut
 
 
-# Descriptions:
-#    Arguments: $self $args
-# Side Effects:
+# Descriptions: top level dispatcher to drive database update
+#    Arguments: OBJ($self) OBJ($msg)
+# Side Effects: update databases
 # Return Value: none
 sub update_db
 {
@@ -507,6 +522,10 @@ sub update_db
 }
 
 
+# Descriptions: speculate unixtime from header
+#    Arguments: OBJ($msg)
+# Side Effects: none
+# Return Value: NUM(unix time)
 sub _speculate_time
 {
     my ($msg) = @_;
@@ -522,10 +541,10 @@ sub _speculate_time
 }
 
 
-# Descriptions:
-#    Arguments: $self $args
-# Side Effects:
-# Return Value: none
+# Descriptions: update database
+#    Arguments: OBJ($self) OBJ($msg)
+# Side Effects: update database
+# Return Value: STR
 sub _update_db
 {
     my ($self, $msg) = @_;
@@ -580,9 +599,9 @@ sub _update_db
 
 # Descriptions: register myself to index_db for further reference
 #               among mailing lists
-#    Arguments: $self $args
-# Side Effects:
-# Return Value: none
+#    Arguments: OBJ($self)
+# Side Effects: update object
+# Return Value: STR
 sub _update_index_db
 {
     my ($self) = @_;
diff --git a/fml/lib/Mail/ThreadTrack/DB.pm b/fml/lib/Mail/ThreadTrack/DB.pm
index 17256916..425c2528 100644
--- a/fml/lib/Mail/ThreadTrack/DB.pm
+++ b/fml/lib/Mail/ThreadTrack/DB.pm
@@ -4,7 +4,7 @@
 #   All rights reserved. This program is free software; you can
 #   redistribute it and/or modify it under the same terms as Perl itself.
 #
-# $FML: DB.pm,v 1.16 2001/12/21 07:34:06 tmu Exp $
+# $FML: DB.pm,v 1.17 2001/12/22 09:21:20 fukachan Exp $
 #
 
 package Mail::ThreadTrack::DB;
@@ -50,9 +50,9 @@ my @kind_of_databases = qw(thread_id date status sender articles
                            message_id);
 
 
-# Descriptions:
-#    Arguments: $self
-# Side Effects:
+# Descriptions: open database by tie() 
+#    Arguments: OBJ($self)
+# Side Effects: none
 # Return Value: none
 sub db_open
 {
@@ -89,9 +89,9 @@ sub db_open
 }
 
 
-# Descriptions:
-#    Arguments: $self
-# Side Effects:
+# Descriptions: clear database
+#    Arguments: OBJ($self)
+# Side Effects: update database
 # Return Value: none
 sub db_clear
 {
@@ -106,9 +106,9 @@ sub db_clear
 }
 
 
-# Descriptions:
-#    Arguments: $directory
-# Side Effects:
+# Descriptions: clear database
+#    Arguments: STR($db_dir)
+# Side Effects: clear database, remove file if needed
 # Return Value: none
 sub _db_clear
 {
@@ -136,9 +136,9 @@ sub _db_clear
 }
 
 
-# Descriptions:
-#    Arguments: $self
-# Side Effects:
+# Descriptions: close database by untie()
+#    Arguments: OBJ($self)
+# Side Effects: none
 # Return Value: none
 sub db_close
 {
@@ -160,9 +160,15 @@ sub db_close
 
 =head2 db_mkdb($min, $max)
 
+remake database.
+
 =cut
 
 
+# Descriptions: remake database for messages from $min_id to $max_id
+#    Arguments: OBJ($self) NUM($min_id) NUM($max_id)
+# Side Effects: remake database
+# Return Value: none
 sub db_mkdb
 {
     my ($self, $min_id, $max_id) = @_;
@@ -208,6 +214,10 @@ dump status database if $type is not specified.
 =cut
 
 
+# Descriptions: dump data for database $type
+#    Arguments: OBJ($self) STR($type)
+# Side Effects: none
+# Return Value: none
 sub db_dump
 {
     my ($self, $type) = @_;
@@ -228,6 +238,10 @@ return HASH REFERENCE for specified $type.
 =cut
 
 
+# Descriptions: get HASH REFERENCE for specified $type.
+#    Arguments: OBJ($self) STR($db_type)
+# Side Effects: none
+# Return Value: STR or UNDEF
 sub db_hash
 {
     my ($self, $db_type) = @_;
diff --git a/fml/lib/Tie/JournaledDir.pm b/fml/lib/Tie/JournaledDir.pm
index 87adc894..e8df92a8 100644
--- a/fml/lib/Tie/JournaledDir.pm
+++ b/fml/lib/Tie/JournaledDir.pm
@@ -4,7 +4,7 @@
 #   All rights reserved. This program is free software; you can
 #   redistribute it and/or modify it under the same terms as Perl itself.
 #
-# $FML: JournaledDir.pm,v 1.5 2001/11/27 15:19:40 fukachan Exp $
+# $FML: JournaledDir.pm,v 1.6 2001/12/22 09:21:22 fukachan Exp $
 #
 
 package Tie::JournaledDir;
@@ -81,14 +81,14 @@ my $debug = $ENV{'debug'} ? 1 :0;
 
 
 # Descriptions: constructor
-#    Arguments: $self $args
+#    Arguments: OBJ($self) HASH_REF($args)
 #               $args = {
 #                    dir => directory path,
 #                   unit => number (seconds)
 #                  limit => number (days)
 #               }
 # Side Effects: import _match_style into $self
-# Return Value: object
+# Return Value: OBJ
 sub new
 {
     my ($self, $args) = @_;
@@ -113,9 +113,9 @@ sub new
 
 
 # Descriptions: generate a cache file
-#    Arguments: (number, directory path, number)
+#    Arguments: NUM($unit) STR($dir) NUM($i)
 # Side Effects: none
-# Return Value: file path
+# Return Value: STR(file path)
 sub _file_name
 {
     my ($unit, $dir, $i) = @_;
@@ -136,9 +136,9 @@ sub _file_name
 
 
 # Descriptions: call new()
-#    Arguments: $self $args
+#    Arguments: OBJ($self) HASH_REF($args)
 # Side Effects: same as new()
-# Return Value: object returned by new()
+# Return Value: OBJ
 sub TIEHASH
 {
     my ($self, $args) = @_;
@@ -149,9 +149,9 @@ sub TIEHASH
 # Descriptions: hash{} access to file in the cache directory
 #               by Tie::JournaledFile sequentially.
 #               XXX file list in the directory is given by new().
-#    Arguments: $self $key
+#    Arguments: OBJ($self) STR($key)
 # Side Effects: none
-# Return Value: key string
+# Return Value: STR
 sub FETCH
 {
     my ($self, $key) = @_;
@@ -179,9 +179,9 @@ sub FETCH
 
 # Descriptions: add { $key => $value } to the latest file
 #               by Tie::JournaledFile.
-#    Arguments: $self $key $value
+#    Arguments: OBJ($self) STR($key) STR($value)
 # Side Effects: none
-# Return Value: Tie::JournaledFile->STORE() operation return value
+# Return Value: STR(Tie::JournaledFile->STORE() operation return value)
 sub STORE
 {
     my ($self, $key, $value) = @_;
@@ -197,10 +197,10 @@ sub STORE
 
 
 # Descriptions: find key in file
-#    Arguments: $self
+#    Arguments: OBJ($self)
 # Side Effects: update object and negative cache in $self
 #               where the cache is file list already searched
-# Return Value: key string
+# Return Value: STR(key string)
 sub __find_key
 {
     my ($self) = @_;
@@ -266,7 +266,7 @@ sub __find_key
 
 
 # Descriptions: object for cache file is alive
-#    Arguments: $self
+#    Arguments: OBJ($self)
 # Side Effects: none
 # Return Value: 1 or 0
 sub __in_valid_search
@@ -277,9 +277,9 @@ sub __in_valid_search
 
 
 # Descriptions: return the first key in the latest file
-#    Arguments: $self
+#    Arguments: OBJ($self)
 # Side Effects: initialize _key_files{done,obj}
-# Return Value: key string
+# Return Value: STR(key string)
 sub FIRSTKEY
 {
     my ($self) = @_;
@@ -303,9 +303,9 @@ sub FIRSTKEY
 
 # Descriptions: fetch the next key in the cache
 #               file to search changes automatically by Tie::JournaledFile.
-#    Arguments: $self
+#    Arguments: OBJ($self)
 # Side Effects: none
-# Return Value: key string
+# Return Value: STR(key string)
 sub NEXTKEY
 {
     my ($self) = @_;
diff --git a/fml/lib/Tie/JournaledFile.pm b/fml/lib/Tie/JournaledFile.pm
index 8c964dba..c35fc942 100644
--- a/fml/lib/Tie/JournaledFile.pm
+++ b/fml/lib/Tie/JournaledFile.pm
@@ -4,7 +4,7 @@
 #   All rights reserved. This program is free software; you can
 #   redistribute it and/or modify it under the same terms as Perl itself.
 #
-# $FML: JournaledFile.pm,v 1.10 2001/08/21 10:04:10 fukachan Exp $
+# $FML: JournaledFile.pm,v 1.11 2001/12/22 09:21:22 fukachan Exp $
 #
 
 package Tie::JournaledFile;
@@ -73,9 +73,9 @@ my $debug = $ENV{'debug'} ? 1 : 0;
 
 
 # Descriptions: constructor
-#    Arguments: $self $args
+#    Arguments: OBJ($self) HASH_REF($args)
 # Side Effects: import _match_style into $self
-# Return Value: object
+# Return Value: OBJ
 sub new
 {
     my ($self, $args) = @_;
@@ -102,6 +102,10 @@ sub new
 }
 
 
+# Descriptions: tie() operation stars
+#    Arguments: OBJ($self) HASH_REF($args)
+# Side Effects: initialize object
+# Return Value: OBJ
 sub TIEHASH
 {
     my ($self, $args) = @_;
@@ -111,6 +115,10 @@ sub TIEHASH
 }
 
 
+# Descriptions: tie() fetch op
+#    Arguments: OBJ($self) STR($key)
+# Side Effects: none
+# Return Value: STR
 sub FETCH
 {
     my ($self, $key) = @_;
@@ -118,6 +126,10 @@ sub FETCH
 }
 
 
+# Descriptions: tie() store op
+#    Arguments: OBJ($self) STR($key) STR($value)
+# Side Effects: none
+# Return Value: STR
 sub STORE
 {
     my ($self, $key, $value) = @_;
@@ -125,6 +137,10 @@ sub STORE
 }
 
 
+# Descriptions: tie() keys op
+#    Arguments: OBJ($self)
+# Side Effects: none
+# Return Value: STR
 sub FIRSTKEY
 {
     my ($self) = @_;
@@ -149,6 +165,10 @@ sub FIRSTKEY
 }
 
 
+# Descriptions: tie() keys op (next op)
+#    Arguments: OBJ($self)
+# Side Effects: none
+# Return Value: STR
 sub NEXTKEY
 {
     my ($self) = @_;
@@ -207,6 +227,10 @@ parameter at C<new()> method. C<first_match> by default.
 =cut
 
 
+# Descriptions: return the array of line(s) with the specified key.
+#    Arguments: OBJ($self) STR($key)
+# Side Effects: none
+# Return Value: ARRAY
 sub find
 {
     my ($self, $key) = @_;
@@ -220,11 +244,11 @@ sub find
 #               return the value with the $key
 #               $self->{ '_match_style' } conrolls the matching algorithm
 #               is either of the fist or last match.
-#    Arguments: $self $key $mode
+#    Arguments: OBJ($self) STR($key) STR($mode)
 #               $key is the string to search.
 #               $mode selects the return value style, scalar or array.
 # Side Effects: none
-# Return Value: SCALAR or ARRAY with the key
+# Return Value: SCALAR or ARRAY
 sub _fetch
 {
     my ($self, $key, $mode) = @_;
@@ -281,10 +305,10 @@ sub _fetch
 
 # Descriptions: wrapper to put "key => value" pair to cache file.
 #               It emulates hash value upates.
-#    Arguments: $self $key $value
+#    Arguments: OBJ($self) STR($key) STR($value)
 #               that is, $key => $value
 # Side Effects: update cache file by _puts()
-# Return Value: return value from _puts()
+# Return Value: same as _puts()
 sub _store
 {
     my ($self, $key, $value) = @_;
@@ -293,7 +317,7 @@ sub _store
 
 
 # Descriptions: append given string to cache file
-#    Arguments: $self $string
+#    Arguments: OBJ($self) STR($string)
 # Side Effects: update cache file
 # Return Value: 1 or throw exception by croak()
 sub _puts