clean up documents

11 files changed, 161 insertions, 61 deletions

diff --git a/fml/lib/FML/Credential.pm b/fml/lib/FML/Credential.pm
index b7c6697b..2c5b30e1 100644
--- a/fml/lib/FML/Credential.pm
+++ b/fml/lib/FML/Credential.pm
@@ -4,8 +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. 
 #
-# $Id$
-# $FML: Credential.pm,v 1.8 2001/04/15 09:07:12 fukachan Exp $
+# $FML: Credential.pm,v 1.9 2001/05/04 14:32:32 fukachan Exp $
 #
 
 package FML::Credential;
@@ -18,7 +17,7 @@ use ErrorStatus qw(errstr error error_set error_clear);
 
 =head1 NAME
 
-FML::Credential - authenticate the mail sender is a ML member or not
+FML::Credential - authenticate the mail sender
 
 =head1 SYNOPSIS
 
diff --git a/fml/lib/FML/MIME.pm b/fml/lib/FML/MIME.pm
index 43af8322..02bff08c 100644
--- a/fml/lib/FML/MIME.pm
+++ b/fml/lib/FML/MIME.pm
@@ -4,8 +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. 
 #
-# $Id$
-# $FML$
+# $FML: MIME.pm,v 1.11 2001/04/03 09:45:40 fukachan Exp $
 #
 
 package FML::MIME;
@@ -26,6 +25,8 @@ FML::MIME - handle a MIME encoded string
 =head1 DESCRIPTION
 
 MIME utilities to encode and decode string.
+It uses C<MIME::Base64> and C<MIME::QuotedPrint> as encoding/decoding
+engines.
 
 =head1 METHODS
 
@@ -71,7 +72,7 @@ sub decode_mime_string
 }
 
 
-=head2 C<decode_mime_string(string, [$options])>
+=head2 C<encode_mime_string(string, [$options])>
 
 encode the C<string> by the encoder $options->{ encode }.
 The encode is base64 by default.
@@ -104,6 +105,7 @@ sub encode_mime_string
     return $buf;
 }
 
+
 sub _encode_mime_string
 {
     my ($str, $options) = @_;
@@ -117,7 +119,7 @@ sub _encode_mime_string
 
     if ($encode eq 'base64') {
 	$header .= '?B?';
-	$str = encode_base64($str);
+	$str     = encode_base64($str);
     }
     elsif ($encode eq 'qp') {
 	$header .= '?Q?';
diff --git a/fml/lib/FML/Mailer.pm b/fml/lib/FML/Mailer.pm
index e231cf24..f2ff5fe3 100644
--- a/fml/lib/FML/Mailer.pm
+++ b/fml/lib/FML/Mailer.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: Mailer.pm,v 1.3 2001/05/18 14:59:21 fukachan Exp $
+# $FML: Mailer.pm,v 1.4 2001/05/19 03:29:57 fukachan Exp $
 #
 
 package FML::Mailer;
@@ -27,9 +27,9 @@ FML::Mailer - Utilities to send mails
 	message   => $message,
     });
 
-where C<$message> is a C<Mail::Message> object to be sent. 
-If you sent plural recipinets, you can pass the list of recipients by
-HASH ARRAY.
+where C<$message> is a C<Mail::Message> object to send. 
+If you want to sent plural recipinets, specify ARRAY HASH of the
+recipients as a C<recipient> parameter.
 
     $obj->send( {
 	sender     => 'rudo@nuinui.net',
@@ -37,7 +37,7 @@ HASH ARRAY.
 	message    => $message,
     });
 
-If you send a file, 
+If you send a file, you can specify the filename as a data to send.
 
     use FML::Mailer;
     my $obj = new FML::Mailer;
@@ -53,7 +53,7 @@ If you send a file,
 
 =head2 C<new()>
 
-usual constructor.
+ordinary constructor.
 
 =cut
 
@@ -69,7 +69,15 @@ sub new
 
 =head2 C<send($args)>
 
-method to send the given C<message>.
+send the given C<message>. 
+$args can take the following arguments:
+
+   ----------------------------------
+   sender             string
+   recipient          string 
+   recipients         HASH ARRAY
+   message            Mail::Message object 
+   file               string
 
 =cut
 
diff --git a/fml/lib/FML/Messages.pm b/fml/lib/FML/Messages.pm
index a7540006..f690292d 100644
--- a/fml/lib/FML/Messages.pm
+++ b/fml/lib/FML/Messages.pm
@@ -4,8 +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. 
 #
-# $Id$
-# $FML$
+# $FML: Messages.pm,v 1.7 2001/04/03 09:45:40 fukachan Exp $
 #
 
 package FML::Messages;
@@ -21,11 +20,16 @@ FML::Messages - manipulate fml system messages
 
 =head1 SYNOPSIS
 
-NOT YET IMPLEMENTED
+   use FML::Messages;
 
 =head1 DESCRIPTION
 
-NOT YET IMPLEMENTED
+C<FML::Messages> is a wrapper.
+It tranlates the error message to specifield language.
+
+=head1 METHODS
+
+   not implemented yet...
 
 =cut
 
diff --git a/fml/lib/FML/Process/CGI.pm b/fml/lib/FML/Process/CGI.pm
index a35900f3..051ae55c 100644
--- a/fml/lib/FML/Process/CGI.pm
+++ b/fml/lib/FML/Process/CGI.pm
@@ -4,8 +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. 
 #
-# $Id$
-# $FML$
+# $FML: CGI.pm,v 1.12 2001/04/03 09:45:43 fukachan Exp $
 #
 
 package FML::Process::CGI;
@@ -26,13 +25,14 @@ FML::Process::CGI - CGI basic functions
 
 =head1 DESCRIPTION
 
-the base class of CGI programs
+the base class of CGI programs.
+It provides basic functions and flow.
 
 =head1 METHODS
 
 =head2 C<new()>
 
-constructor which is usual in FML::Process classes.
+ordinary constructor which is used widely in FML::Process classes.
 
 =cut
 
@@ -43,7 +43,7 @@ use FML::Config;
 # load standard CGI routines
 use CGI qw/:standard/;
 
-@ISA = qw(FML::Process::Kernel Exporter);
+@ISA = qw(FML::Process::Kernel);
 
 
 # XXX now we re-evaluate $ml_home_dir and @cf again.
@@ -75,6 +75,7 @@ sub new
 =head2 C<prepare()>
 
 print HTTP header.
+The charset is C<euc-jp> by default.
 
 =cut
 
@@ -92,11 +93,11 @@ sub prepare
 
 =head2 C<verify_request()>
 
-a dummy method
+dummy method now.
 
 =head2 C<finish()>
 
-dummy method
+dummy method now.
 
 =cut
 
@@ -104,6 +105,12 @@ sub verify_request { 1;}
 sub finish { 1;}
 
 
+=head2 C<run()>
+
+dispatch *.cgi programs.
+
+=cut
+
 # See CGI.pm for more details
 sub run
 {
diff --git a/fml/lib/FML/Process/Command.pm b/fml/lib/FML/Process/Command.pm
index 804c171b..85cfb9c4 100644
--- a/fml/lib/FML/Process/Command.pm
+++ b/fml/lib/FML/Process/Command.pm
@@ -1,10 +1,10 @@
 #!/usr/local/bin/perl -w
 #-*- perl -*-
 #
-# Copyright (C) 2000 Ken'ichi Fukamachi
+# Copyright (C) 2000,2001 Ken'ichi Fukamachi
 #          All rights reserved. 
 #
-# $FML: Command.pm,v 1.8 2001/04/03 09:45:43 fukachan Exp $
+# $FML: Command.pm,v 1.9 2001/04/06 16:25:43 fukachan Exp $
 #
 
 package FML::Process::Command;
@@ -22,24 +22,38 @@ use FML::Config;
 
 =head1 NAME
 
-FML::Process::Command -- fml5 command wrapper.
+FML::Process::Command -- fml5 command dispacher.
 
 =head1 SYNOPSIS
 
    use FML::Process::Command;
    ...
 
-See L<FML::Process::Flow> for details of flow.
+See L<FML::Process::Flow> for details of fml process flow.
 
 =head1 DESCRIPTION
 
 C<FML::Process::Command> is a command wrapper and top level
-dispatcher.
-It kicks off C<FML::Command>->C<$command($curproc, $args)> for each
-C<$command>.
+dispatcher for commands.
+It kicks off corresponding 
+C<FML::Command>->C<$command($curproc,$args)> 
+for the given C<$command>.
+
+=head1 METHODS
+
+=head2 C<new($args)>
+
+make fml process object.
+
+    my $curproc = new FML::Process::Kernel $args;
+
+=head2 C<prepare($args)>
+
+forward the request to SUPER CLASS.
 
 =cut
 
+
 sub new
 {
     my ($self, $args) = @_;
@@ -56,6 +70,12 @@ sub prepare
 }
 
 
+=head2 C<verify_request($args)>
+
+verify the sender is a valid member or not.
+
+=cut
+
 sub verify_request
 {
     my ($curproc, $args) = @_;
@@ -63,6 +83,17 @@ sub verify_request
 }
 
 
+=head2 C<run($args)>
+
+dispatcher to run correspondig C<FML::Command::command> for
+C<command>.
+
+    lock
+    execute FML::Command::command
+    unlock
+
+=cut
+
 sub run
 {
     my ($curproc, $args) = @_;
@@ -81,6 +112,12 @@ sub run
 }
 
 
+=head2 C<finish($args)>
+
+    $curproc->inform_reply_messages();
+
+=cut
+
 sub finish
 {
     my ($curproc, $args) = @_;
@@ -128,4 +165,23 @@ sub _evaluate_command
 }
 
 
+=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::Command 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/QMail.pm b/fml/lib/FML/Process/QMail.pm
index 043e1072..fecf5527 100644
--- a/fml/lib/FML/Process/QMail.pm
+++ b/fml/lib/FML/Process/QMail.pm
@@ -4,8 +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. 
 #
-# $Id$
-# $FML$
+# $FML: QMail.pm,v 1.7 2001/04/03 09:45:43 fukachan Exp $
 #
 
 package FML::Process::QMail;
@@ -36,6 +35,16 @@ C<NOT YET IMPLERMENTED>.
 
 C<NOT YET IMPLERMENTED>.
 
+=head1 TODO
+
+   XXX
+   XXX MEMO on TODO
+   XXX
+
+   we should not use "# command" representation even though internally.
+
+   check $ext more restrictly.
+
 =head1 METHODS
 
 =cut
diff --git a/fml/lib/FML/Process/Switch.pm b/fml/lib/FML/Process/Switch.pm
index e189be09..9009aef2 100644
--- a/fml/lib/FML/Process/Switch.pm
+++ b/fml/lib/FML/Process/Switch.pm
@@ -4,8 +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. 
 #
-# $Id$
-# $FML: Switch.pm,v 1.17 2001/04/05 08:30:27 fukachan Exp $
+# $FML: Switch.pm,v 1.18 2001/04/15 13:30:02 fukachan Exp $
 #
 
 package FML::Process::Switch;
@@ -17,11 +16,11 @@ use vars qw($debug);
 
 =head1 NAME
 
-FML::Process::Switch - switch or dispather table to run the suitable library
+FML::Process::Switch - dispatch the suitable library
 
 =head1 SYNOPSIS
 
-(in libexec/loader)
+used in C<libexec/loader>.
 
    package main;
    use FML::Process::Switch;
@@ -32,15 +31,19 @@ FML::Process::Switch - switch or dispather table to run the suitable library
 C<libexec/loader> (C<libexec/fml/loader>), the wrapper, loads this
 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.
+analyzes the command arguments
+and call C<ProcessSwitch()> finally.
+
+C<ProcessSwitch()> emulates "use $package" to load 
+the corresponding library with the arguments.
 The fml flow bifurcates here through C<ProcessSwitch()>.
 
-The details of each program exists in FML::Process:: class.
+The flow details of program exists in FML::Process:: class.
 For example, libexec/distribute (fml.pl) runs in this way.
-   
+
+       functions                class   
+       ----------------------------------------
+
        main::Bootstrap()        libexec/loader
             |
             V
@@ -63,7 +66,8 @@ It reads *.cf files, parses them and set the result to C<@cf>
 array variable.
 We pass it to C<ProcessSwitch()> later.
 
-    @cf = ( /etc/fml/defaults/$VERSION/default_config.cf 
+    @cf = (
+	   /etc/fml/defaults/$VERSION/default_config.cf 
 	   /etc/fml/site_default_config.cf (required ?)
 	   /etc/fml/domains/$DOMAIN/default_config.cf
 	   /var/spool/ml/elena/config.cf
@@ -246,6 +250,14 @@ sub _makefml_parse_argv
 
 =head2 C<ProcessSwitch($args)> 
 
+load the library and prepare environment to use it.
+C<ProcessSwitch($args)> return process object C<$obj>.
+
+To start the process, we pass C<$obj> with C<$args> to 
+C<FML::Process::Flow::ProcessStart($obj, $args)>.
+
+C<$args> is like this:
+
     my $args = {
 	fml_version    => $main_cf->{ fml_version },
 	
diff --git a/fml/lib/File/Rotate.pm b/fml/lib/File/Rotate.pm
index c7a243c9..d44b6646 100644
--- a/fml/lib/File/Rotate.pm
+++ b/fml/lib/File/Rotate.pm
@@ -4,8 +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. 
 #
-# $Id$
-# $FML$
+# $FML: Rotate.pm,v 1.5 2001/04/03 09:31:27 fukachan Exp $
 #
 
 package File::Rotate;
@@ -18,7 +17,7 @@ END   {}
 
 =head1 NAME
 
-File::Rotate - file rotate operations
+File::Rotate - file rotatation utilities
 
 =head1 SYNOPSIS
 
@@ -31,6 +30,7 @@ File::Rotate - file rotate operations
 =head1 DESCRIPTION
 
 Utility functions for file rotate operations. 
+It turns over the given C<file>.
 C<rotation> renames and rearranges files like this:
 
     rm file.4
@@ -40,8 +40,20 @@ C<rotation> renames and rearranges files like this:
     mv file.0 file.1
     mv file   file.0
 
+=head1 METHODS
+
+=head2 C<new($args)>
+
+ordinary constructor. $args accpets the following parameters.
+
+   parameter       default value
+   ------------------------
+   max_size        300*1024
+   num_backlog     4
+
 =cut
 
+
 # Descriptions: constructor
 #               forward new() request to superclass (IO::File)
 #    Arguments: $class_name $HASH_REFERENCE
diff --git a/fml/lib/File/SimpleLock.pm b/fml/lib/File/SimpleLock.pm
index 4b546d2e..a283d582 100644
--- a/fml/lib/File/SimpleLock.pm
+++ b/fml/lib/File/SimpleLock.pm
@@ -1,9 +1,8 @@
 #-*- perl -*- 
 # 
-# Copyright (C) 2000 Ken'ichi Fukamachi 
+# Copyright (C) 2000,2001 Ken'ichi Fukamachi 
 # 
-# $Id$ 
-# $FML: SimpleLock.pm,v 1.6 2001/04/03 09:31:27 fukachan Exp $ 
+# $FML: SimpleLock.pm,v 1.7 2001/04/08 13:25:39 fukachan Exp $ 
 #
 
 package File::SimpleLock;
diff --git a/regress/simulation/todo/doc b/regress/simulation/todo/doc
index 74f3947f..7073902a 100644
--- a/regress/simulation/todo/doc
+++ b/regress/simulation/todo/doc
@@ -1,7 +1,7 @@
-$FML$
+$FML: doc,v 1.42 2001/05/27 14:41:07 fukachan Exp $
 
 	TODO for documents
-	$Date$
+	Last Modified: $Date$
 
 ---------------
 2001/05 todo (document clean up)
@@ -11,25 +11,17 @@ $FML$
 	FML/Checksum.pm
 	FML/Credential.pm
 	FML/Header/Subject.pm
-	FML/MIME.pm
-	FML/Mailer.pm
 	FML/MemberControl.pm
-	FML/Messages.pm
-	FML/Process/CGI.pm
-	FML/Process/Command.pm
 	FML/Process/Configure.pm
 	FML/Process/Distribute.pm
 	FML/Process/DocViewer.pm
 	FML/Process/Flow.pm
 	FML/Process/Kernel.pm
-	FML/Process/QMail.pm
 	FML/Process/QueueManager.pm
-	FML/Process/Switch.pm
 	FML/Process/TicketSystem.pm
 	FML/Ticket/Model/minimal_states.pm
 	FML/Ticket/System.pm
 	File/Rotate.pm
-	File/SimpleLock.pm
 	IO/Adapter.pm
 	IO/Adapter/Array.pm
 	IO/Adapter/DBI.pm