update documents, comments

9 files changed, 297 insertions, 115 deletions

diff --git a/fml/lib/FML/Log.pm b/fml/lib/FML/Log.pm
index 7e6127eb..6450f5f8 100644
--- a/fml/lib/FML/Log.pm
+++ b/fml/lib/FML/Log.pm
@@ -2,7 +2,7 @@
 #
 # Copyright (C) 2000 Ken'ichi Fukamachi
 #
-# $FML: Log.pm,v 1.13 2001/11/27 15:19:39 fukachan Exp $
+# $FML: Log.pm,v 1.14 2001/12/22 09:21:01 fukachan Exp $
 #
 
 package FML::Log;
@@ -13,7 +13,6 @@ require Exporter;
 
 use strict;
 use Carp;
-use Mail::Message::Date;
 use FML::Config;
 use FML::Credential;
 
@@ -73,22 +72,35 @@ same as Log("error: $message", $args);
 =cut
 
 
+# Descriptions: write message $msg to logfile
+#    Arguments: STR($msg) HASH_REF($args)
+# Side Effects: update logfile
+# Return Value: none
 sub Log
 {
     my ($mesg, $args) = @_;
-    my $config = new FML::Config;
+    my $config   = new FML::Config;
+    my $log_file = '';
+    my $priority = '';
+    my $facility = '';
+    my $level    = '';
+    my $rdate    = '';
 
-    # parse arguments
-    my $log_file = $args->{ log_file };
-    my $priority = $args->{ priority };
-    my $facility = $args->{ facility };
-    my $level    = $args->{ level };
+    # simple check: null $mesg string is invalid.
+    return undef unless defined $mesg;
+    return undef unless $mesg;
 
-    # invalid calling
-    $mesg || return undef ;
+    # parse arguments
+    $log_file = $args->{ log_file } if defined $args->{ log_file };
+    $priority = $args->{ priority } if defined $args->{ priority };
+    $facility = $args->{ facility } if defined $args->{ facility };
+    $level    = $args->{ level }    if defined $args->{ level };
 
     # reference to "date" object
-    my $rdate = new Mail::Message::Date;
+    eval q{ 
+	use Mail::Message::Date;
+	$rdate = new Mail::Message::Date;
+    };
 
     # open the $file by using FileHandle.pm
     use FileHandle;
@@ -118,6 +130,10 @@ sub Log
 }
 
 
+# Descriptions: write message "warn: $msg", call Log() ASAP
+#    Arguments: STR($msg) HASH_REF($args)
+# Side Effects: none
+# Return Value: none
 sub LogWarn
 {
     my ($mesg, $args) = @_;
@@ -125,6 +141,10 @@ sub LogWarn
 }
 
 
+# Descriptions: write message "error: $msg", call Log() ASAP
+#    Arguments: STR($msg) HASH_REF($args)
+# Side Effects: none
+# Return Value: none
 sub LogError
 {
     my ($mesg, $args) = @_;
diff --git a/fml/lib/FML/Process/CGI/Kernel.pm b/fml/lib/FML/Process/CGI/Kernel.pm
index 70b26ab6..1a242213 100644
--- a/fml/lib/FML/Process/CGI/Kernel.pm
+++ b/fml/lib/FML/Process/CGI/Kernel.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: Kernel.pm,v 1.9 2001/11/25 09:06:31 fukachan Exp $
+# $FML: Kernel.pm,v 1.10 2001/12/22 09:21:10 fukachan Exp $
 #
 
 package FML::Process::CGI::Kernel;
@@ -47,9 +47,13 @@ ordinary constructor which is used widely in FML::Process classes.
 =cut
 
 
-# XXX now we re-evaluate $ml_home_dir and @cf again.
-# XXX but we need the mechanism to re-evaluate $args passed from
-# XXX libexec/loader.
+# Descriptions: constructor.
+#               now we re-evaluate $ml_home_dir and @cf again.
+#               but we need the mechanism to re-evaluate $args passed from
+#               libexec/loader.
+#    Arguments: OBJ($self) HASH_REF($args)
+# Side Effects: none
+# Return Value: OBJ
 sub new
 {
     my ($self, $args) = @_;
@@ -87,8 +91,12 @@ The charset is C<euc-jp> by default.
 =cut
 
 
-# XXX FML::Process::Kernel::prepare() parses incoming_message
-# XXX CGI do not parse incoming_message;
+# Descriptions: html header.
+#               FML::Process::Kernel::prepare() parses incoming_message
+#               CGI do not parse incoming_message;
+#    Arguments: OBJ($curproc)
+# Side Effects: none
+# Return Value: none
 sub prepare
 {
     my ($curproc) = @_;
@@ -132,6 +140,13 @@ run() executes
 =cut
 
 
+# Descriptions: run FML::CGI::* methods
+#                  html_start()
+#                  run_cgi()
+#                  html_end()
+#    Arguments: OBJ($curproc) HASH_REF($args)
+# Side Effects: none
+# Return Value: none
 sub run
 {
     my ($curproc, $args) = @_;
@@ -149,6 +164,10 @@ get HASH ARRAY of valid mailing lists.
 =cut
 
 
+# Descriptions: list up ML 
+#    Arguments: OBJ($curproc) HASH_REF($args)
+# Side Effects: none
+# Return Value: HASH_ARRAY
 sub get_ml_list
 {
     my ($curproc, $args) = @_;
@@ -176,6 +195,10 @@ get and filter param('xxx') via AUTOLOAD().
 =cut
 
 
+# Descriptions: trap safe_param_XXX()
+#    Arguments: OBJ($curproc)
+# Side Effects: callback to safe_param*().
+# Return Value: depend on safe_param*() return value
 sub AUTOLOAD
 {
     my ($curproc) = @_;
diff --git a/fml/lib/FML/Process/CGI/Param.pm b/fml/lib/FML/Process/CGI/Param.pm
index d7e289fd..4fae4a1d 100644
--- a/fml/lib/FML/Process/CGI/Param.pm
+++ b/fml/lib/FML/Process/CGI/Param.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: Param.pm,v 1.9 2001/11/25 11:29:33 fukachan Exp $
+# $FML: Param.pm,v 1.10 2001/12/22 09:21:10 fukachan Exp $
 #
 
 package FML::Process::CGI::Param;
@@ -17,37 +17,30 @@ use CGI qw/:standard/;
 
 =head1 NAME
 
-FML::Process::CGI::Param - CGI basic functions
+FML::Process::CGI::Param - CGI input restriction
 
 =head1 SYNOPSIS
 
-   use FML::Process::CGI::Param;
-   my $obj = new FML::Process::CGI::Param;
-   $obj->prepare($args);
-      ... snip ...
-
-This new() creates CGI object which wraps C<FML::Process::Param>.
+See FML::CGI:: on usage.
 
 =head1 DESCRIPTION
 
-the base class of CGI programs.
-It provides basic functions and flow.
+cleaner for data.
 
 =head1 METHODS
 
-=head2 safe_param(str, filter)
-
-=cut
+=head2 safe_param(str, key)
 
+return value for key if the value is appropriate.
 
-my $debug = defined $ENV{'debug'} ? 1 : 0;
+=cut
 
 
-# Descriptions:
-#    Arguments: $self $args
-# Side Effects:
-#      History: fml 4.0's SecureP()
-# Return Value: none
+# Descriptions: return value for key if the value is appropriate.
+#    Arguments: OBJ($self) STR($key)
+# Side Effects: none
+#      History: similar to fml 4.0's SecureP() and libcgi_cleanup.pl
+# Return Value: STR
 sub safe_param
 {
     my ($self, $key) = @_;
@@ -57,8 +50,6 @@ sub safe_param
     my $safe_param_regexp  = $safe->param_regexp();
     my $safe_method_regexp = $safe->method_regexp();
 
-    print STDERR "\n<!-- check param $key -->\n" if $debug;
-
     if (defined $safe_param_regexp->{ $key }) {
 	if (defined param($key)) {
 	    my $value  = param($key);
@@ -82,11 +73,18 @@ sub safe_param
 }
 
 
-# Descriptions:
-#    Arguments: $self $args
-# Side Effects:
-#      History: fml 4.0's SecureP()
-# Return Value: none
+=head2 safe_paramlist($self, $numregexp, $key)
+
+return HASH_ARRAY for $key.
+
+=cut
+
+
+# Descriptions: return HASH_ARRAY for key if the value is appropriate.
+#    Arguments: OBJ($self) NUM($numregexp) STR($key)
+# Side Effects: none
+#      History: similar to fml 4.0's SecureP() and libcgi_cleanup.pl
+# Return Value: HASH_ARRAY
 sub safe_paramlist
 {
     my ($self, $numregexp, $key) = @_;
diff --git a/fml/lib/FML/Process/Distribute.pm b/fml/lib/FML/Process/Distribute.pm
index 2ec13c68..f5d58015 100644
--- a/fml/lib/FML/Process/Distribute.pm
+++ b/fml/lib/FML/Process/Distribute.pm
@@ -3,7 +3,7 @@
 # Copyright (C) 2000,2001 Ken'ichi Fukamachi
 #          All rights reserved.
 #
-# $FML: Distribute.pm,v 1.57 2001/12/18 12:56:05 fukachan Exp $
+# $FML: Distribute.pm,v 1.58 2001/12/22 09:21:09 fukachan Exp $
 #
 
 package FML::Process::Distribute;
@@ -41,15 +41,16 @@ where C<$obj> is the object C<FML::Process::$module::new()> returns.
 
 create C<FML::Process::Distribute> object.
 C<$curproc> is the object C<FML::Process::Kernel> returns but
-we bless it as C<FML::Process::Distribute> object.
+we bless it as C<FML::Process::Distribute> object again.
 
 =cut
 
+
 # Descriptions: constructor.
 #               sub class of FML::Process::Kernel
-#    Arguments: $self $args
+#    Arguments: OBJ($self) HASH_REF($args)
 # Side Effects: none
-# Return Value: FML::Process::Distribute object
+# Return Value: OBJ(FML::Process::Distribute)
 sub new
 {
     my ($self, $args) = @_;
@@ -65,8 +66,9 @@ forward the request to the base class.
 
 =cut
 
+
 # Descriptions: prepare miscellaneous work before the main routine starts
-#    Arguments: $self $args
+#    Arguments: OBJ($self) HASH_REF($args)
 # Side Effects: none
 # Return Value: none
 sub prepare
@@ -82,9 +84,10 @@ check the mail sender and the mail loop possibility.
 
 =cut
 
+
 # Descriptions: verify the mail sender and others
-#    Arguments: $self $args
-# Side Effects: none
+#    Arguments: OBJ($curproc) HASH_REF($args)
+# Side Effects: lock
 # Return Value: none
 sub verify_request
 {
@@ -107,8 +110,9 @@ Lastly we unlock the current process.
 
 =cut
 
-# Descriptions: the main routine
-#    Arguments: $self $args
+
+# Descriptions: the main routine, kick off _distribute()
+#    Arguments: OBJ($curproc) HASH_REF($args)
 # Side Effects: distribution of articles.
 #               See _distribute() for more details.
 # Return Value: none
@@ -158,9 +162,11 @@ If needed, we send back error messages to the mail sender.
 
 =cut
 
-# Descriptions: clean up in the end of the curreen process
-#    Arguments: $self $args
-# Side Effects: none
+
+# Descriptions: clean up in the end of the curreen process.
+#               return error messages et. al.
+#    Arguments: OBJ($curproc) HASH_REF($args)
+# Side Effects: queue flush
 # Return Value: none
 sub finish
 {
@@ -176,7 +182,7 @@ sub finish
 #                  $article->header_rewrite();
 #                  $article->increment_id();
 #                  $article->spool();
-#    Arguments: $self $args
+#    Arguments: OBJ($curproc) HASH_REF($args)
 # Side Effects: header rewrite
 #               the article sequence number is incremanted
 #               article spooling.
@@ -221,9 +227,9 @@ sub _distribute
 
 
 # Descriptions: build and return FML::Article object
-#    Arguments: $self $args
+#    Arguments: OBJ($curproc) HASH_REF($args)
 # Side Effects: none
-# Return Value: FML::Article object
+# Return Value: OBJ(FML::Article)
 sub _prepare_article
 {
     my ($curproc, $args) = @_;
@@ -239,7 +245,7 @@ sub _prepare_article
 # Descriptions: header rewrite followed by
 #               $config->{ article_header_rewrite_rules }
 #               each method exists in FML::Header module.
-#    Arguments: $self $args
+#    Arguments: OBJ($curproc) HASH_REF($args)
 # Side Effects: $curproc->{ article }->{ header } is rewritten
 # Return Value: none
 sub _header_rewrite
@@ -268,8 +274,8 @@ sub _header_rewrite
 
 
 # Descriptions: deliver the article
-#    Arguments: $self $args
-# Side Effects: smtp logging
+#    Arguments: OBJ($curproc) HASH_REF($args)
+# Side Effects: mail delivery, logging
 # Return Value: none
 sub _deliver_article
 {
@@ -335,7 +341,7 @@ sub _deliver_article
 
 
 # Descriptions: the top level interface to drive thread tracking system
-#    Arguments: $self $args
+#    Arguments: OBJ($curproc) HASH_REF($args)
 # Side Effects: update thread information
 # Return Value: none
 sub _thread_check
@@ -373,6 +379,10 @@ sub _thread_check
 }
 
 
+# Descriptions: the top level entry to create HTML article
+#    Arguments: OBJ($curproc) HASH_REF($args)
+# Side Effects: update html database
+# Return Value: none
 sub htmlify
 {
     my ($curproc, $args) = @_;
@@ -403,6 +413,7 @@ sub htmlify
     }
 }
 
+
 =head1 AUTHOR
 
 Ken'ichi Fukamachi
diff --git a/fml/lib/FML/Process/Kernel.pm b/fml/lib/FML/Process/Kernel.pm
index e4b40011..7e3697c4 100644
--- a/fml/lib/FML/Process/Kernel.pm
+++ b/fml/lib/FML/Process/Kernel.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: Kernel.pm,v 1.65 2001/12/22 03:20:39 fukachan Exp $
+# $FML: Kernel.pm,v 1.66 2001/12/22 09:21:09 fukachan Exp $
 #
 
 package FML::Process::Kernel;
@@ -68,7 +68,7 @@ use File::SimpleLock;
 push(@ISA, qw(FML::Process::Utils));
 
 # Descriptions: constructor
-#    Arguments: $self $args
+#    Arguments: OBJ($self) HASH_REF($args)
 # Side Effects: none
 # Return Value: FML::Process::Kernel object
 sub new
@@ -160,7 +160,7 @@ sub new
 
 
 # Descriptions: set up default signal handling
-#    Arguments: $self $args
+#    Arguments: OBJ($curproc) HASH_REF($args)
 # Side Effects: none
 # Return Value: none
 sub _signal_init
@@ -177,7 +177,7 @@ sub _signal_init
 
 
 # Descriptions: show help and exit here, (ASAP)
-#    Arguments: $self $args
+#    Arguments: OBJ($curproc) HASH_REF($args)
 # Side Effects: longjmp() to help
 # Return Value: none
 sub _trap_help
@@ -205,7 +205,7 @@ a set of the header and the body object.
 =cut
 
 # Descriptions: preliminary works before the main part
-#    Arguments: $self $args
+#    Arguments: OBJ($curproc) HASH_REF($args)
 # Side Effects: none
 # Return Value: same as parse_incoming_message()
 sub prepare
@@ -228,7 +228,7 @@ It is a giant lock now.
 =cut
 
 # Descriptions:
-#    Arguments: $self $args
+#    Arguments: OBJ($curproc) HASH_REF($args)
 # Side Effects:
 # Return Value: none
 sub lock
@@ -273,7 +273,7 @@ sub lock
 
 
 # Descriptions:
-#    Arguments: $self $args
+#    Arguments: OBJ($curproc) HASH_REF($args)
 # Side Effects:
 # Return Value: none
 sub unlock
@@ -302,7 +302,7 @@ If valid, it sets the adddress within $curproc->{ credential } object.
 =cut
 
 # Descriptions:
-#    Arguments: $self $args
+#    Arguments: OBJ($curproc) HASH_REF($args)
 # Side Effects:
 # Return Value: none
 sub verify_sender_credential
@@ -342,7 +342,7 @@ See C<FML::Header> object for more details.
 =cut
 
 # Descriptions: top level of loop checks
-#    Arguments: $self $args
+#    Arguments: OBJ($curproc) HASH_REF($args)
 # Side Effects: none
 # Return Value: none
 sub simple_loop_check
@@ -379,7 +379,7 @@ $config->get() of FETCH() method is called.
 =cut
 
 # Descriptions: load configuration files and evaluate variables
-#    Arguments: $self $args
+#    Arguments: OBJ($curproc) HASH_REF($args)
 # Side Effects: none
 # Return Value: none
 sub load_config_files
@@ -417,7 +417,7 @@ The C<body> is C<Mail::Message> object.
 =cut
 
 # Descriptions: parse the message to a set of header and body
-#    Arguments: $self $args
+#    Arguments: OBJ($curproc) HASH_REF($args)
 # Side Effects: $curproc->{'incoming_message'} is set up
 # Return Value: none
 sub parse_incoming_message
@@ -627,7 +627,7 @@ Prepare the message and queue it in by C<Mail::Delivery::Queue>.
 #               $r  = get(message, queue)
 #               msg = header + "text" + $r->[0] + $r->[1] + ...
 #
-#    Arguments: $self $args
+#    Arguments: OBJ($curproc) HASH_REF($args)
 # Side Effects:
 # Return Value: none
 sub inform_reply_messages
@@ -650,6 +650,10 @@ sub inform_reply_messages
 =cut
 
 
+# Descriptions: queue in. queueing only not delivered.
+#    Arguments: OBJ($curproc) STR($category) HASH_REF($optargs)
+# Side Effects: add message into queue
+# Return Value: OBJ(queue object)
 sub queue_in
 {
     my ($curproc, $category, $optargs) = @_;
@@ -742,6 +746,10 @@ sub queue_in
 }
 
 
+# Descriptions: add some info into header
+#    Arguments: OBJ($config) OBJ($msg)
+# Side Effects: none
+# Return Value: none
 sub _add_info_on_header
 {
     my ($config, $msg) = @_;
@@ -769,6 +777,11 @@ C<TODO:>
 
 =cut
 
+
+# Descriptions: flush all queue.
+#    Arguments: OBJ($curproc) OBJ($queue)
+# Side Effects: none
+# Return Value: none
 sub queue_flush
 {
     my ($curproc, $queue) = @_;
@@ -806,7 +819,7 @@ C<Caution:>
 #               2. expand variables: $ml_name -> elena
 #               3. back kanji code: euc -> iso-2022-jp
 #               4. return the new created template
-#    Arguments: $self $filename_string $args
+#    Arguments: OBJ($curproc) HASH_REF($args)
 # Side Effects: none
 # Return Value: a new filepath (string) to be prepared
 sub prepare_file_to_return
@@ -847,6 +860,11 @@ return the object for C<$module>.
 
 =cut
 
+
+# Descriptions: load module
+#    Arguments: OBJ($curpros) HASH_REF($args) STR($pkg)
+# Side Effects: load module
+# Return Value: OBJ
 sub load_module
 {
     my ($curproc, $args, $pkg) = @_;
diff --git a/fml/lib/FML/Process/QueueManager.pm b/fml/lib/FML/Process/QueueManager.pm
index abe648a4..f1ce165a 100644
--- a/fml/lib/FML/Process/QueueManager.pm
+++ b/fml/lib/FML/Process/QueueManager.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: QueueManager.pm,v 1.4 2001/09/13 14:43:28 fukachan Exp $
+# $FML: QueueManager.pm,v 1.5 2001/12/22 09:21:09 fukachan Exp $
 #
 
 package FML::Process::QueueManager;
@@ -26,13 +26,12 @@ or if you send specific queue C<$queue_id>, use
 
     $obj->send($curproc, $queue_id);
 
-where C<$queue_id> is like this 1000390413.14775.1 not file path.
+where C<$queue_id> is queue id such as 1000390413.14775.1, 
+not file path.
 
 =head1 DESCRIPTION
 
-not yet implemented.
-
-Now it can send a mail in queue.
+queue flush!
 
 =head1 METHODS
 
@@ -42,9 +41,14 @@ constructor.
 
 =cut
 
+
 use FML::Log qw(Log LogWarn LogError);
 
 
+# Descriptions: standard constructor
+#    Arguments: OBJ($self) HASH_REF($args)
+# Side Effects: none
+# Return Value: OBJ
 sub new
 {
     my ($self, $args) = @_;
@@ -64,6 +68,11 @@ If queue id C<$id> is specified, send queue for C<$id>.
 
 =cut
 
+
+# Descriptions: send message in queue directory sequentially
+#    Arguments: OBJ($self) OBJ($curproc) HASH_REF($args)
+# Side Effects: queue flush-ed
+# Return Value: none
 sub send
 {
     my ($self, $curproc, $id) = @_;
@@ -95,6 +104,10 @@ sub send
 }
 
 
+# Descriptions: send message object $q
+#    Arguments: OBJ($self) OBJ($curproc) OBJ($q)
+# Side Effects: queue flush-ed
+# Return Value: STR
 sub _send
 {
     my ($self, $curproc, $q) = @_;
diff --git a/fml/lib/FML/Process/Switch.pm b/fml/lib/FML/Process/Switch.pm
index ebf23972..f6710b04 100644
--- a/fml/lib/FML/Process/Switch.pm
+++ b/fml/lib/FML/Process/Switch.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: Switch.pm,v 1.48 2001/12/22 09:21:10 fukachan Exp $
+# $FML: Switch.pm,v 1.49 2001/12/22 16:10:00 fukachan Exp $
 #
 
 package FML::Process::Switch;
@@ -16,7 +16,7 @@ use vars qw($debug);
 
 =head1 NAME
 
-FML::Process::Switch - dispatch the suitable library
+FML::Process::Switch - dispatch the suitable module
 
 =head1 SYNOPSIS
 
@@ -35,7 +35,7 @@ analyzes the command arguments
 and call C<ProcessSwitch()> finally.
 
 C<ProcessSwitch()> emulates "use $package" to load
-the corresponding library with the arguments.
+module suitable with the arguments.
 The fml flow bifurcates here through C<ProcessSwitch()>.
 
 The flow details of program exists in FML::Process:: class.
@@ -77,10 +77,9 @@ We pass it to C<ProcessSwitch()> later.
 
 
 # Descriptions: the second phase of bootstrap
-#    Arguments: $main_cf_file
-#               /etc/fml/main.cf in typical case.
+#    Arguments: STR($main_cf_file) HASH_REF($main_cf)
 # Side Effects: none
-# Return Value: the same as FML::Process::Flow::ProcessStart()
+# Return Value: same as FML::Process::Flow::ProcessStart()
 sub main::Bootstrap2
 {
     my ($main_cf_file, $main_cf) = @_;
@@ -195,9 +194,9 @@ sub main::Bootstrap2
 
 
 # Descriptions: analyze argument vector
-#    Arguments: $main_cf_file_name
+#    Arguments: STR($myname) HASH_REF($main_cf)
 # Side Effects: none
-# Return Value: ARRAY REFERENCE (a list of config.cf's)
+# Return Value: HASH_ARRAY (list of config.cf's)
 sub _parse_argv
 {
     my ($myname, $main_cf) = @_;
@@ -211,6 +210,10 @@ sub _parse_argv
 }
 
 
+# Descriptions: analyze argument vector
+#    Arguments: STR($myname) HASH_REF($main_cf)
+# Side Effects: none
+# Return Value: HASH_ARRAY (list of config.cf's)
 sub _usual_parse_argv
 {
     my ($myname, $main_cf) = @_;
@@ -253,6 +256,10 @@ sub _usual_parse_argv
 }
 
 
+# Descriptions: analyze argument vector
+#    Arguments: STR($myname) HASH_REF($main_cf)
+# Side Effects: none
+# Return Value: HASH_ARRAY (list of config.cf's)
 sub _makefml_parse_argv
 {
     my ($myname, $main_cf) = @_;
@@ -326,11 +333,10 @@ C<$args> is like this:
 # Descriptions: top level process switch
 #               emulates "use $package" but $package is dynamically
 #               determined by e.g. $0.
-#    Arguments: $args
-#               XXX non OO interface
+#    Arguments: HASH_REF($args)
 # Side Effects: process switching :-)
 #               ProcessSwtich() is exported to main:: Name Space.
-# Return Value: package name
+# Return Value: STR(package name)
 sub ProcessSwitch
 {
     my ($args) = @_;
@@ -353,9 +359,9 @@ sub ProcessSwitch
 
 
 # Descriptions: return the suitable getopt options
-#    Arguments: $myname (determined by $0)
+#    Arguments: STR($myname)
 # Side Effects: none
-# Return Value: getopt parameters
+# Return Value: ARRAY (getopt parameters)
 sub _module_specific_options
 {
     my ($myname) = @_;
@@ -412,7 +418,7 @@ sub _module_specific_options
 
 
 # Descriptions: this program ($0) requires ML name always or not?
-#    Arguments: $myname ($0)
+#    Arguments: STR($myname)
 # Side Effects: none
 # Return Value: 1 (require ml name always) or 0
 sub _ml_name_is_required
@@ -435,10 +441,9 @@ sub _ml_name_is_required
 
 
 # Descriptions: determine package we need and require() it if needed.
-#    Arguments: $args
-#               XXX non OO interface
+#    Arguments: HASH_REF($args)
 # Side Effects: none
-# Return Value: FML::Process::SOMETHING module name
+# Return Value: STR(FML::Process::SOMETHING module name)
 sub _module_we_use
 {
     my ($args) = @_;
diff --git a/fml/lib/FML/Process/ThreadTrack.pm b/fml/lib/FML/Process/ThreadTrack.pm
index 63aff0a9..92177ad4 100644
--- a/fml/lib/FML/Process/ThreadTrack.pm
+++ b/fml/lib/FML/Process/ThreadTrack.pm
@@ -3,7 +3,7 @@
 # Copyright (C) 2000-2001 Ken'ichi Fukamachi
 #          All rights reserved.
 #
-# $FML: ThreadTrack.pm,v 1.17 2001/11/27 11:40:30 fukachan Exp $
+# $FML: ThreadTrack.pm,v 1.18 2001/12/22 09:21:10 fukachan Exp $
 #
 
 package FML::Process::ThreadTrack;
@@ -44,6 +44,10 @@ dummy.
 =cut
 
 
+# Descriptions: standard constructor
+#    Arguments: OBJ($self) HASH_REF($args)
+# Side Effects: none
+# Return Value: OBJ
 sub new
 {
     my ($self, $args) = @_;
@@ -54,8 +58,8 @@ sub new
 
 
 # Descriptions: dummy to avoid to take data from STDIN
-#    Arguments: $self $args
-# Side Effects:
+#    Arguments: OBJ($self) HASH_REF($args)
+# Side Effects: none
 # Return Value: none
 sub prepare
 {
@@ -69,6 +73,11 @@ call the actual thread tracking system.
 
 =cut
 
+
+# Descriptions: switch of commands to use Mail::ThreadTrack module
+#    Arguments: OBJ($curproc) HASH_REF($args)
+# Side Effects: load module
+# Return Value: none
 sub run
 {
     my ($curproc, $args) = @_;
@@ -183,6 +192,10 @@ sub _speculate_last_id
 }
 
 
+# Descriptions: speculate maximum sequence number for ML article
+#    Arguments: OBJ($curproc) STR($spool_dir)
+# Side Effects: none
+# Return Value: NUM
 sub _speculate_max_id
 {
     my ($curproc, $spool_dir) = @_;
@@ -218,6 +231,10 @@ sub _speculate_max_id
 }
 
 
+# Descriptions: read filter list
+#    Arguments: OBJ($thread) STR($file)
+# Side Effects: none
+# Return Value: none
 sub _read_filter_list
 {
     my ($thread, $file) = @_;
@@ -240,8 +257,12 @@ sub _read_filter_list
 }
 
 
-# $thread_id accepts MH style format.
-# MH style is expanded by C<Mail::Messsage::MH>.
+# Descriptions: change status to "closed".
+#               $thread_id accepts MH style format.
+#               MH style is expanded by C<Mail::Messsage::MH>.
+#    Arguments: OBJ($self) HASH_REF($args)
+# Side Effects: update thread status database
+# Return Value: none
 sub _close
 {
     my ($thread, $thread_id, $min, $max) = @_;
@@ -267,6 +288,10 @@ sub _close
 }
 
 
+# Descriptions: show help
+#    Arguments: none
+# Side Effects: none
+# Return Value: none
 sub help
 {
     use File::Basename;
@@ -289,11 +314,7 @@ _EOF_
 
 sub DESTROY {}
 
-# Descriptions: dummy routine to avoid errors
-#               since we need all methods defined in FML::Process::Flow.
-#    Arguments: $self $args
-# Side Effects: none
-# Return Value: none
+
 sub AUTOLOAD
 {
     my ($curproc, $args) = @_;
@@ -308,6 +329,11 @@ use strict;
 use Carp;
 
 
+# Descriptions: top level interface for CUI.
+#               This routine is in loop.
+#    Arguments: OBJ($curproc) HASH_REF($args) OBJ($thread) HASH_REF($ttargs)
+# Side Effects: none
+# Return Value: none
 sub interactive
 {
     my ($curproc, $args, $thread, $ttargs) = @_;
@@ -332,6 +358,12 @@ sub interactive
 }
 
 
+# Descriptions: CUI command switch
+#    Arguments: OBJ($curproc) HASH_REF($args)
+#               OBJ($xthread) HASH_REF($ttargs)
+#               STR($buf)
+# Side Effects: exit for some type of input.
+# Return Value: none
 sub _exec
 {
     my ($curproc, $args, $xthread, $ttargs, $buf) = @_;
@@ -386,10 +418,10 @@ sub _exec
 }
 
 
-#
-# commands
-#
-
+# Descriptions: show CUI help
+#    Arguments: none
+# Side Effects: none
+# Return Value: none
 sub help
 {
     print "Usage: $0\n\n";
diff --git a/fml/lib/FML/Process/Utils.pm b/fml/lib/FML/Process/Utils.pm
index 2dfb2b4f..5eedf406 100644
--- a/fml/lib/FML/Process/Utils.pm
+++ b/fml/lib/FML/Process/Utils.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: Utils.pm,v 1.4 2001/11/09 10:39:40 fukachan Exp $
+# $FML: Utils.pm,v 1.5 2001/12/22 09:21:10 fukachan Exp $
 #
 
 package FML::Process::Utils;
@@ -16,19 +16,47 @@ use FML::Log qw(Log LogWarn LogError);
 
 =head1 NAME
 
-FML::Process::Utils - small utilities
+FML::Process::Utils - small utilities for FML::Process::
 
 =head1 SYNOPSIS
 
-=head1 DESCRIPTION
+See FML::Process::Kernel.
 
-=head1 TODO
+=head1 DESCRIPTION
 
 =head1 METHODS
 
+=head2 fml_version()
+
+return fml version.
+
+=head2 myname()
+
+return current process name.
+
+=head2 command_line_raw_argv()
+
+@ARGV before getopts() analyze.
+
+=head2 command_line_argv()
+
+@ARGV after getopts() analyze.
+
+=head2 command_line_argv_find(pat)
+
+search pattern in @ARGV and return it if found.
+
+=head2 command_line_options()
+
+return options, result of getopts() analyze.
+
 =cut
 
 
+# Descriptions: return fml version
+#    Arguments: OBJ($curproc)
+# Side Effects: none
+# Return Value: STR
 sub fml_version
 {
     my ($curproc) = @_;
@@ -38,6 +66,10 @@ sub fml_version
 }
 
 
+# Descriptions: return current process name
+#    Arguments: OBJ($curproc)
+# Side Effects: none
+# Return Value: STR
 sub myname
 {
     my ($curproc) = @_;
@@ -47,6 +79,11 @@ sub myname
 }
 
 
+# Descriptions: return raw @ARGV of current process,
+#               where @ARGV is before getopts() applied
+#    Arguments: OBJ($curproc)
+# Side Effects: none
+# Return Value: HASH_ARRAY
 sub command_line_raw_argv
 {
     my ($curproc) = @_;
@@ -56,6 +93,11 @@ sub command_line_raw_argv
 }
 
 
+# Descriptions: return @ARGV of current process,
+#               where @ARGV is after getopts() applied
+#    Arguments: OBJ($curproc)
+# Side Effects: none
+# Return Value: HASH_ARRAY
 sub command_line_argv
 {
     my ($curproc) = @_;
@@ -65,6 +107,11 @@ sub command_line_argv
 }
 
 
+# Descriptions: search string matched with specified pattern and
+#               return it.
+#    Arguments: OBJ($curproc) STR($pat)
+# Side Effects: none
+# Return Value: STR or UNDEF
 sub command_line_argv_find
 {
     my ($curproc, $pat) = @_;
@@ -82,6 +129,10 @@ sub command_line_argv_find
 }
 
 
+# Descriptions: options, which is the result by getopts() analyze
+#    Arguments: OBJ($curproc)
+# Side Effects: none
+# Return Value: HASH_ARRAY
 sub command_line_options
 {
     my ($curproc) = @_;
@@ -91,6 +142,17 @@ sub command_line_options
 }
 
 
+=head2 article_id_max()
+
+return the current article number (sequence number).
+
+=cut
+
+
+# Descriptions: return the current article number (sequence number)
+#    Arguments: OBJ($curproc)
+# Side Effects: none
+# Return Value: NUM
 sub article_id_max
 {
     my ($curproc) = @_;