clean up document

4 files changed, 199 insertions, 36 deletions

diff --git a/fml/lib/FML/Process/Distribute.pm b/fml/lib/FML/Process/Distribute.pm
index 8b4fbcec..f467c94f 100644
--- a/fml/lib/FML/Process/Distribute.pm
+++ b/fml/lib/FML/Process/Distribute.pm
@@ -24,20 +24,35 @@ FML::Process::Distribute -- fml5 article distributer library.
 
 =head1 SYNOPSIS
 
-   use FML::Process::Command;
+   use FML::Process::Distribute;
    ...
 
-See L<FML::Process::Flow> for details of flow.
+See L<FML::Process::Flow> for details of the fml flow.
 
 =head1 DESCRIPTION
 
-=cut
+C<FML::Process::Flow::ProcessStart($pkg, $args)> drives the fml flow
+where C<$pkg> is the object C<FML::Process::$module::new()> returns.
 
+=cut
 
 require Exporter;
 @ISA = qw(FML::Process::Kernel Exporter);
 
 
+=head2 C<new($args)>
+
+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.
+
+=cut
+
+# Descriptions: constructor.
+#               sub class of FML::Process::Kernel
+#    Arguments: $self $args
+# Side Effects: none
+# Return Value: FML::Process::Distribute object
 sub new
 {
     my ($self, $args) = @_;
@@ -47,6 +62,16 @@ sub new
 }
 
 
+=head2 C<prepare($args)>
+
+forward the request to the base class.
+
+=cut
+
+# Descriptions: prepare miscellaneous work before the main routine starts
+#    Arguments: $self $args
+# Side Effects: none
+# Return Value: none
 sub prepare
 {
     my ($self, $args) = @_;
@@ -54,6 +79,16 @@ sub prepare
 }
 
 
+=head2 C<verify_request($args)>
+
+check the mail sender and the mail loop possibility.
+
+=cut
+
+# Descriptions: verify the mail sender and others
+#    Arguments: $self $args
+# Side Effects: none
+# Return Value: none
 sub verify_request
 {
     my ($curproc, $args) = @_;
@@ -62,6 +97,22 @@ sub verify_request
 }
 
 
+=head2 C<run($args>)
+
+Firstly it locks (giant lock) the current process.
+
+If the mail sender is one of our mailing list member,
+we can distribute the mail as an article.
+
+Lastly we unlock the current process.
+
+=cut
+
+# Descriptions: the main routine
+#    Arguments: $self $args
+# Side Effects: distribution of articles.
+#               See _distribute() for more details.
+# Return Value: none
 sub run
 {
     my ($curproc, $args) = @_;
@@ -81,6 +132,17 @@ sub run
 }
 
 
+=head2 C<finish($args)>
+
+send back or inform reply messages to the mail sender, for example,
+error messages.
+
+=cut
+
+# Descriptions: clean up in the end of the curreen process
+#    Arguments: $self $args
+# Side Effects: none
+# Return Value: none
 sub finish
 {
     my ($curproc, $args) = @_;
@@ -89,10 +151,16 @@ sub finish
 }
 
 
-# $article->header_rewrite;
-# $article->increment_id;
-# $article->spool;
-# distribute( $article );
+# Descriptions: the top level routine to drive the article spooling and
+#               distribution.
+#                  $article->header_rewrite();
+#                  $article->increment_id();
+#                  $article->spool();
+#    Arguments: $self $args
+# Side Effects: header rewrite
+#               the article sequence number is incremanted
+#               article spooling. 
+# Return Value: none
 sub _distribute
 {
     my ($curproc, $args) = @_;
@@ -127,6 +195,10 @@ sub _distribute
 }
 
 
+# Descriptions: build and return FML::Article object
+#    Arguments: $self $args
+# Side Effects: none
+# Return Value: FML::Article object
 sub _prepare_article
 {
     my ($curproc, $args) = @_;
@@ -139,6 +211,12 @@ sub _prepare_article
 }
 
 
+# Descriptions: header rewrite followed by
+#               $config->{ article_header_rewrite_rules }
+#               each method exists in FML::Header module.
+#    Arguments: $self $args
+# Side Effects: $curproc->{ article }->{ header } is rewritten
+# Return Value: none
 sub _header_rewrite
 {
     my ($curproc, $args) = @_;
@@ -164,13 +242,17 @@ sub _header_rewrite
 }
 
 
+# Descriptions: deliver the article
+#    Arguments: $self $args
+# Side Effects: smtp logging
+# Return Value: none
 sub _deliver_article
 {
     my ($curproc, $args) = @_;
 
-    my $config  = $curproc->{ config };             # FML::Config object;
-    my $body    = $curproc->{ article }->{ body };  # MailingList::Messages object;
-    my $header  = $curproc->{ article }->{ header };# FML::Header object;
+    my $config  = $curproc->{ config };             # FML::Config obj
+    my $body    = $curproc->{ article }->{ body };  # MailingList::Messages obj
+    my $header  = $curproc->{ article }->{ header };# FML::Header obj
 	
     unless ( $config->yes( 'use_article_delivery' ) ) {
 	return;
@@ -226,6 +308,10 @@ sub _deliver_article
 }
 
 
+# Descriptions: the top level interface to drive ticket system
+#    Arguments: $self $args
+# Side Effects: update ticket information
+# Return Value: none
 sub _ticket_check
 {
     my ($curproc, $args) = @_;    
@@ -260,4 +346,23 @@ sub _ticket_check
 }
 
 
+=head1 AUTHOR
+
+Ken'ichi Fukamachi
+
+=head1 COPYRIGHT
+
+Copyright (C) 2001 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
+
+FML::Process::Distribute appeared in fml5 mailing list driver package.
+See C<http://www.fml.org/> for more details.
+
+=cut
+
+
 1;
diff --git a/fml/lib/FML/Process/Switch.pm b/fml/lib/FML/Process/Switch.pm
index 80b81a11..87b9708c 100644
--- a/fml/lib/FML/Process/Switch.pm
+++ b/fml/lib/FML/Process/Switch.pm
@@ -21,28 +21,37 @@ FML::Process::Switch - switch or dispather table to run the suitable library
 
 =head1 SYNOPSIS
 
-   require "$libexec_dir/process_switch";
-   ProcessSwitch( {
-       fml_version    => $main_cf->{ fml_version },
+(in libexec/loader)
 
-       myname         => $myname,
-       ml_home_prefix => $main_cf->{ ml_home_prefix },
-       ml_home_dir    => $ml_home_dir,
-
-       cf_list        => \@cf,
-       options        => \%options,
-   });
-
-See also C<libexec/fml/loader>.
+   package main;
+   use FML::Process::Switch;
+   &Bootstrap2($main_cf_file); # main::Bootstrap2()
 
 =head1 DESCRIPTION
 
 C<libexec/loader> (C<libexec/fml/loader>), the wrapper, loads this
-program and calls C<Bootstrap2()> and C<ProcessSwitch()>.
+program and calls C<Bootstrap2()>.
+C<Bootstrap2()> loads main.cf,
+analyzes the command argument
+and kicks off C<ProcessSwitch()> finally.
 C<ProcessSwitch()> emulates "use $package" to load a program specified
 by the arguments.
+The fml flow bifurcates here through C<ProcessSwitch()>.
 
 The details of each program exists in FML::Process:: class.
+For example, libexec/distribute (fml.pl) runs in this way.
+   
+       main::Bootstrap()        libexec/loader
+            |
+            V
+       main::Bootstrap2()       Process::Switch
+            |
+            V
+       ProcessSwitch()          Process::Switch
+            |
+            V
+       FML::Process:Distribute  FML::Process::Distribute
+
 
 =head1 FUNCTIONS
 
@@ -63,6 +72,11 @@ We pass it to C<ProcessSwitch()> later.
 =cut
 
 
+# Descriptions: the second phase of bootstrap
+#    Arguments: $main_cf_file
+#               /etc/fml/main.cf in typical case.
+# Side Effects: none
+# Return Value: the same as FML::Process::Flow::ProcessStart()
 sub main::Bootstrap2
 {
     my ($main_cf_file)    = @_;
@@ -74,7 +88,7 @@ sub main::Bootstrap2
     use File::Basename;
     my $myname            = basename($0); # inspect my name from $0
 
-    # 2.0 parse command line options (preliminary)
+    # 1.0 parse command line options (preliminary)
     use Getopt::Long;
     GetOptions(\%options, _module_specific_options($myname));
 
@@ -126,14 +140,18 @@ sub main::Bootstrap2
 	need_ml_name   => _ml_name_is_required($myname),
     };
 
-    # See libexec/process_switch on ProcessSwitch()
-    my $pkg = ProcessSwitch($args);
+    # get the object. The suitable module is speculcated by $0.
+    my $obj = ProcessSwitch($args);
 
-    # See FML::Process::Kernel module on ProcessStart()
-    FML::Process::Flow::ProcessStart($pkg, $args);
+    # start the process.
+    FML::Process::Flow::ProcessStart($obj, $args);
 }
 
 
+# Descriptions: 
+#    Arguments: $self $args
+# Side Effects: 
+# Return Value: none
 sub _parse_argv
 {
     my ($main_cf) = @_;
@@ -142,8 +160,8 @@ sub _parse_argv
     my $found_cf       = 0;
     my @cf             = ();
 
+    # "elena" is translated to "/var/spool/ml/elena"
     for (@ARGV) {
-	# elena is translated to "/var/spool/ml/elena"
 	unless ($found_cf) {
 	    my $x = "$ml_home_prefix/$_";
 	    if (-d $x && -f "$x/config.cf") {
@@ -172,6 +190,34 @@ sub _parse_argv
 }
 
 
+=head2 C<ProcessSwitch($args)> 
+
+    my $args = {
+        fml_version    => $main_cf->{ fml_version },
+        
+        myname         => $myname,
+        ml_home_prefix => $main_cf->{ ml_home_prefix },
+        ml_home_dir    => $main_cf->{ ml_home_dir },
+        
+        cf_list        => $cf,
+        options        => \%options,
+
+        # pass the original information to each process
+        argv           => \@argv,
+        ARGV           => \@ARGV,
+
+        # options
+        need_ml_name   => _ml_name_is_required($myname),
+    };
+
+    # get the object. The suitable module is speculcated by $0.
+    my $obj = ProcessSwitch($args);
+
+    # start the process.
+    FML::Process::Flow::ProcessStart($obj, $args);
+
+=cut
+
 # Descriptions: top level process switch
 #               emulates "use $package" but $package is dynamically 
 #               determined by e.g. $0.
@@ -197,6 +243,10 @@ sub ProcessSwitch
 }
 
 
+# Descriptions: return the suitable getopt options
+#    Arguments: $myname (determined by $0)
+# Side Effects: none
+# Return Value: getopt parameters
 sub _module_specific_options
 {
     my ($myname) = @_;
@@ -220,6 +270,10 @@ sub _module_specific_options
 }
 
 
+# Descriptions: this program ($0) requires ML name always or not?
+#    Arguments: $myname ($0)
+# Side Effects: none
+# Return Value: 1 (require ml name always) or 0
 sub _ml_name_is_required
 {
     my ($myname) = @_;
@@ -240,7 +294,7 @@ sub _ml_name_is_required
 #    Arguments: $args
 #               XXX non OO interface
 # Side Effects: none
-# Return Value: FML::Process::SOMETHING process object
+# Return Value: FML::Process::SOMETHING module name
 sub _module_we_use
 {
     my ($args) = @_;    
diff --git a/fml/lib/FML/Ticket/Model/toymodel.pm b/fml/lib/FML/Ticket/Model/toymodel.pm
index 7186f46d..7bc255c7 100644
--- a/fml/lib/FML/Ticket/Model/toymodel.pm
+++ b/fml/lib/FML/Ticket/Model/toymodel.pm
@@ -443,7 +443,7 @@ sub _set_status
 
 
 
-=haead1 OUTPUT ROUTINES
+=head1 OUTPUT ROUTINES
 
 =head2 C<show_summary($curproc, $args>)
 
diff --git a/fml/lib/FML/Ticket/System.pm b/fml/lib/FML/Ticket/System.pm
index 2c063ace..17faed7f 100644
--- a/fml/lib/FML/Ticket/System.pm
+++ b/fml/lib/FML/Ticket/System.pm
@@ -23,13 +23,16 @@ FML::Ticket::System - ticket system core engine
 
 =head1  SYNOPSIS
 
-	use Ticket::Model::toymodel;
-	$ticket = new Ticket::Model::toymodel;
-	$ticket->asign($curproc, $args);
-	$ticket->update_cache($curproc, $args);
+   use Ticket::Model::toymodel;
+   $ticket = new Ticket::Model::toymodel;
+   $ticket->assign($curproc, $args);
+   $ticket->update_cache($curproc, $args);
 
 =head1 DESCRIPTION
 
+the base class of ticket systems.
+This module provides basic functions to help sub classes.
+
 =head2 CLASS HIERARCHY
 
         FML::Ticket::System
@@ -37,13 +40,14 @@ FML::Ticket::System - ticket system core engine
                 A 
        -------------------
        |        |        |
+       A        A        A
     toymodel  model2    ....
 
 =head1 METHODS
 
 =head2 C<new()>
 
-usual constructor.
+the usual constructor.
 
 =cut