update documents, comments

3 files changed, 160 insertions, 106 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) = @_;