update comments, copyright. FNF-ify. sort definition

2 files changed, 107 insertions, 64 deletions

diff --git a/fml/lib/Mail/ThreadTrack/HeaderRewrite.pm b/fml/lib/Mail/ThreadTrack/HeaderRewrite.pm
index 521a406e..12ac4873 100644
--- a/fml/lib/Mail/ThreadTrack/HeaderRewrite.pm
+++ b/fml/lib/Mail/ThreadTrack/HeaderRewrite.pm
@@ -1,10 +1,10 @@
 #-*- perl -*-
 #
-#  Copyright (C) 2001 Ken'ichi Fukamachi
+#  Copyright (C) 2001,2002 Ken'ichi Fukamachi
 #   All rights reserved. This program is free software; you can
 #   redistribute it and/or modify it under the same terms as Perl itself.
 #
-# $FML: HeaderRewrite.pm,v 1.7 2001/11/20 07:29:27 fukachan Exp $
+# $FML: HeaderRewrite.pm,v 1.8 2001/12/22 09:21:20 fukachan Exp $
 #
 
 package Mail::ThreadTrack::HeaderRewrite;
@@ -14,7 +14,7 @@ use Carp;
 
 =head1 NAME
 
-Mail::ThreadTrack::HeaderRewrite - what is this
+Mail::ThreadTrack::HeaderRewrite - header manipulation
 
 =head1 SYNOPSIS
 
@@ -22,8 +22,6 @@ Mail::ThreadTrack::HeaderRewrite - what is this
 
 =head1 METHODS
 
-=cut
-
 =head2 C<rewrite_header($msg)>
 
 C<$msg> is Mail::Message object.
@@ -31,18 +29,10 @@ C<$msg> is Mail::Message object.
 =cut
 
 
-# Descriptions:
-#    Arguments: $self $args
-# Side Effects:
-# Return Value: none
-=head2 rewrite_header($msg)
-
-=cut
-
-
-# Descriptions:
-#    Arguments: $self $msg
-# Side Effects:
+# Descriptions: add thread track info into $msg where
+#               $msg is Mail::Message object.
+#    Arguments: OBJ($self) OBJ($msg)
+# Side Effects: modify $msg header
 # Return Value: none
 sub rewrite_header
 {
@@ -81,9 +71,9 @@ sub rewrite_header
 }
 
 
-# Descriptions: prepare header information
-#    Arguments: $self $msg
-# Side Effects:
+# Descriptions: prepare history infomation for further header rewrite
+#    Arguments: OBJ($self) OBJ($msg)
+# Side Effects: update $self->{ _status_history }
 # Return Value: none
 sub prepare_history_info
 {
@@ -122,7 +112,7 @@ Ken'ichi Fukamachi
 
 =head1 COPYRIGHT
 
-Copyright (C) 2001 Ken'ichi Fukamachi
+Copyright (C) 2001,2002 Ken'ichi Fukamachi
 
 All rights reserved. This program is free software; you can
 redistribute it and/or modify it under the same terms as Perl itself.
diff --git a/fml/lib/Mail/ThreadTrack/Print.pm b/fml/lib/Mail/ThreadTrack/Print.pm
index ba24d614..c9dc4588 100644
--- a/fml/lib/Mail/ThreadTrack/Print.pm
+++ b/fml/lib/Mail/ThreadTrack/Print.pm
@@ -1,10 +1,10 @@
 #-*- perl -*-
 #
-#  Copyright (C) 2001 Ken'ichi Fukamachi
+#  Copyright (C) 2001,2002 Ken'ichi Fukamachi
 #   All rights reserved. This program is free software; you can
 #   redistribute it and/or modify it under the same terms as Perl itself.
 #
-# $FML: Print.pm,v 1.19 2001/11/19 11:26:26 fukachan Exp $
+# $FML: Print.pm,v 1.20 2001/12/22 09:21:20 fukachan Exp $
 #
 
 package Mail::ThreadTrack::Print;
@@ -15,7 +15,7 @@ use Mail::ThreadTrack::Print::Utils qw(decode_mime_string STR2EUC);
 
 =head1 NAME
 
-Mail::ThreadTrack::Print - print out thread relation
+Mail::ThreadTrack::Print - dispatcher to print out thread
 
 =head1 SYNOPSIS
 
@@ -23,9 +23,32 @@ Mail::ThreadTrack::Print - print out thread relation
 
 =head1 METHODS
 
+=head2 list()
+
+show todo list without article summary.
+
+=cut
+
+
+# Descriptions: show todo list without article summary.
+#    Arguments: OBJ($self)
+# Side Effects: none
+# Return Value: none
+sub list
+{
+    my ($self, @opts) = @_;
+
+    $self->_load_library();
+    $self->db_open();
+    $self->_do_list(@opts);
+    $self->db_close();
+}
+
+
 =head2 summary()
 
-show the thread summary.
+show the thread summary, which is todo list C<with> article summary.
+
 Each row that C<show_summary()> returns has a set of
 C<date>, C<age>, C<status>, C<thread-id> and
 C<articles>, which is a list of articles with the thread-id.
@@ -41,45 +64,34 @@ summary show entries by the thread_id order. For example,
  2001/02/07    3.0  going  elena_#00000454       814 815
  2001/02/10    0.1   open  elena_#00000456       821
 
-=head2 review()
-
-show a chain of article summary in each thread.
-
 =cut
 
 
-# Descriptions: top level entrance for "show" mode
-#    Arguments: $self varargs ...
+# Descriptions: show todo list with article summary.
+#    Arguments: OBJ($self)
 # Side Effects: none
 # Return Value: none
-sub list
+sub summary
 {
     my ($self, @opts) = @_;
 
     $self->_load_library();
     $self->db_open();
-    $self->_do_list(@opts);
+    $self->_do_summary(@opts);
     $self->db_close();
 }
 
 
-# Descriptions: top level entrance for "show" mode
-#    Arguments: $self varargs ...
-# Side Effects: none
-# Return Value: none
-sub summary
-{
-    my ($self, @opts) = @_;
+=head2 review()
 
-    $self->_load_library();
-    $self->db_open();
-    $self->_do_summary(@opts);
-    $self->db_close();
-}
+show a chain of article summary in each thread.
+This summary is a collection of short summary of articles in one thread.
+
+=cut
 
 
-# Descriptions: top level entrance for "review" mode
-#    Arguments: $self varargs ...
+# Descriptions: show summary for each thread
+#    Arguments: OBJ($self) VARARGS
 # Side Effects: none
 # Return Value: none
 sub review
@@ -94,8 +106,8 @@ sub review
 
 
 
-# Descriptions: dynamic loading of sub modules
-#    Arguments: $self
+# Descriptions: load subclasses, change @INC
+#    Arguments: OBJ($self)
 # Side Effects: @INC modified
 # Return Value: none
 sub _load_library
@@ -125,6 +137,11 @@ sub _load_library
 # SUMMARY MODE
 #
 
+
+# Descriptions: dispatcher to show todo list with article summary.
+#    Arguments: OBJ($self)
+# Side Effects: none
+# Return Value: none
 sub _do_summary
 {
     my ($self) = @_;
@@ -132,6 +149,10 @@ sub _do_summary
 }
 
 
+# Descriptions: dispatcher to show todo list without article summary.
+#    Arguments: OBJ($self)
+# Side Effects: none
+# Return Value: none
 sub _do_list
 {
     my ($self) = @_;
@@ -139,9 +160,9 @@ sub _do_list
 }
 
 
-# Descriptions: get thread id list with status != 'open' and
+# Descriptions: get thread id list with status != 'close' and
 #               show summary for the list
-#    Arguments: $self
+#    Arguments: OBJ($self) HASH_REF($option)
 # Side Effects: none
 # Return Value: none
 sub __do_summary
@@ -174,9 +195,9 @@ sub __do_summary
 
 
 
-# Descriptions:
-#    Arguments: $self $args
-# Side Effects:
+# Descriptions: show thread summary
+#    Arguments: OBJ($self) ARRAY_REF($thread_id_list)
+# Side Effects: none
 # Return Value: none
 sub _print_thread_summary
 {
@@ -216,7 +237,7 @@ sub _print_thread_summary
 
 
 # Descriptions: show the first few lines of the first message in the thread
-#    Arguments: $self $id
+#    Arguments: OBJ($self) STR($thread_id)
 # Side Effects: none
 # Return Value: none
 sub _print_message_summary
@@ -231,8 +252,8 @@ sub _print_message_summary
 #
 
 # Descriptions: show brief summary chain of messages in the thread
-#    Arguments: $self $string $min_num $max_num
-# Side Effects:
+#    Arguments: OBJ($self) STR($str) NUM($min) NUM($max)
+# Side Effects: none
 # Return Value: none
 sub _do_review
 {
@@ -295,11 +316,17 @@ sub _do_review
 }
 
 
-=head2 show()
+=head2 show($tid)
+
+show all articles in specified thread.
 
 =cut
 
 
+# Descriptions: show all articles in specified thread.
+#    Arguments: OBJ($self) STR($tid)
+# Side Effects: none
+# Return Value: none
 sub show
 {
     my ($self, $tid) = @_;
@@ -311,13 +338,16 @@ sub show
 }
 
 
-=head2 print()
+=head2 print(str)
+
+print str with special effect e.g. quoting if needed.
+The function depends the mode, 'text' or 'html'.
 
 =cut
 
 
 # Descriptions: wrapper of print()
-#    Arguments: $self $str
+#    Arguments: OBJ($self) STR($str)
 # Side Effects: quote if needed
 # Return Value: none
 sub print
@@ -337,10 +367,10 @@ sub print
 }
 
 
-# Descriptions: quote for html
-#    Arguments: $str
-# Side Effects: quote
-# Return Value: string
+# Descriptions: quote for html metachars
+#    Arguments: STR($str)
+# Side Effects: none
+# Return Value: STR
 sub _quote
 {
     my ($str) = @_;
@@ -354,4 +384,27 @@ sub _quote
 }
 
 
+=head1 CODING STYLE
+
+See C<http://www.fml.org/software/FNF/> on fml coding style guide.
+
+=head1 AUTHOR
+
+Ken'ichi Fukamachi
+
+=head1 COPYRIGHT
+
+Copyright (C) 2001,2002 Ken'ichi Fukamachi
+
+All rights reserved. This program is free software; you can
+redistribute it and/or modify it under the same terms as Perl itself.
+
+=head1 HISTORY
+
+Mail::ThreadTrack::Print appeared in fml5 mailing list driver package.
+See C<http://www.fml.org/> for more details.
+
+=cut
+
+
 1;