full documentation (alpha)

1 files changed, 173 insertions, 6 deletions

diff --git a/fml/lib/FML/Process/Kernel.pm b/fml/lib/FML/Process/Kernel.pm
index ff4dda07..0a83fdcc 100644
--- a/fml/lib/FML/Process/Kernel.pm
+++ b/fml/lib/FML/Process/Kernel.pm
@@ -13,8 +13,44 @@ package FML::Process::Kernel;
 use strict;
 use Carp;
 
-use FML::Process::Flow;
+=head1 NAME
+
+FML::Process::Kernel - provide core functions
+
+=head1 SYNOPSIS
+
+    use FML::Process::Kernel;
+    $curproc = new FML::Process::Kernel;
+    $curproc->prepare($args);
+
+=head1 DESCRIPTION
+
+This modules is the base class of fml processes.
+It provides basic core functions.
+See L<FML::Process::Flow> on where and how each function is used 
+in the process flow.
+
+=head1 METHODS
+
+=head2 C<new($args)>
+
+1. import variables from libexec/loader
+   e.g. C<$ml_home_dir>
+
+2. define C<$fml_version>
+
+3. initialize
+    $curproc->{ config }
+    $curproc->{ pcb }
+
+4. load and evaluate configuration files 
+   e.g. /var/spool/ml/elena/config.cf
+
+5. initialize signal handlders
 
+=cut
+
+use FML::Process::Flow;
 use FML::Parse;
 use FML::Header;
 use FML::Config;
@@ -22,7 +58,10 @@ use FML::Log qw(Log);
 use File::SimpleLock;
 use FML::Messages;
 
-
+# Descriptions: constructor
+#    Arguments: $self $args
+# Side Effects: none
+# Return Value: FML::Process::Kernel object
 sub new
 {
     my ($self, $args)    = @_;
@@ -82,7 +121,10 @@ sub new
 }
 
 
-# default signal handling
+# Descriptions: set up default signal handling
+#    Arguments: $self $args
+# Side Effects: none
+# Return Value: none
 sub _signal_init
 {
     my ($curproc, $args) = @_;
@@ -96,13 +138,41 @@ sub _signal_init
 }
 
 
+=head2 C<prepare($args)>
+
+It does preliminary works before the main part.
+It parses the message injected from STDIN to set up
+a set of the header and the body object.
+
+=cut
+
+# Descriptions: preliminary works before the main part
+#    Arguments: $self $args
+# Side Effects: none
+# Return Value: same as parse_incoming_message()
 sub prepare
 {
     my ($curproc, $args) = @_;
-    $curproc->parse_incoming_message();
+    $curproc->parse_incoming_message($args);
 }
 
 
+=head2 C<lock($args)>
+
+locks the current process. 
+It is a giant lock now.
+
+=head2 C<unlock($args)>
+
+unlocks the current process.
+It is a giant lock now.
+
+=cut
+
+# Descriptions: 
+#    Arguments: $self $args
+# Side Effects: 
+# Return Value: none
 sub lock
 {
     my ($curproc, $args) = @_;
@@ -144,6 +214,10 @@ sub lock
 }
 
 
+# Descriptions: 
+#    Arguments: $self $args
+# Side Effects: 
+# Return Value: none
 sub unlock
 {
     my ($curproc, $args) = @_;
@@ -162,18 +236,44 @@ sub unlock
 }
 
 
+=head2 C<inform_reply_messages($args)>
+
+inform the error messages to the sender.
+C<not yet implemented>.
+
+=cut
+
+# Descriptions: 
+#    Arguments: $self $args
+# Side Effects: 
+# Return Value: none
 sub inform_reply_messages
 {
     my ($curproc, $args) = @_;
 }
 
 
-sub ValidateInComingMail
+# Descriptions: 
+#    Arguments: $self $args
+# Side Effects: 
+# Return Value: none
+sub validate_incoming_message
 {
     my ($curproc, $args) = @_;
 }
 
 
+=head2 C<verify_sender_credential($args)>
+
+verify the mail sender and put the adddress at 
+$curproc->{ credential } object.
+
+=cut
+
+# Descriptions: 
+#    Arguments: $self $args
+# Side Effects: 
+# Return Value: none
 sub verify_sender_credential
 {
     my ($curproc, $args) = @_;
@@ -199,6 +299,16 @@ sub verify_sender_credential
 }
 
 
+=head2 C<sender_is_member($args)>
+
+not yet implemented.
+
+=cut
+
+# Descriptions: 
+#    Arguments: $self $args
+# Side Effects: 
+# Return Value: none
 sub sender_is_member
 {
     my ($curproc, $args) = @_;
@@ -207,6 +317,16 @@ sub sender_is_member
 }
 
 
+=head2 C<simple_loop_check($args)>
+
+loop checks following rules of $config->{ header_check_rules }.
+
+=cut
+
+# Descriptions: top level of loop checks
+#    Arguments: $self $args
+# Side Effects: none
+# Return Value: none
 sub simple_loop_check
 {
     my ($curproc, $args) = @_;
@@ -225,7 +345,17 @@ sub simple_loop_check
 }
 
 
-# fml5::init_main() routine
+=head2 C<load_config_files($files)>
+
+load configuration variables from C<@$files> and expand them in the
+last.
+
+=cut
+
+# Descriptions: load configuration files and evaluate variables
+#    Arguments: $self $args
+# Side Effects: none
+# Return Value: none
 sub load_config_files
 {
     my ($curproc, $files) = @_;
@@ -241,6 +371,24 @@ sub load_config_files
 }
 
 
+=head2 C<parse_incoming_message($args)>
+
+parse the message to a set of header and body. 
+$curproc->{'incoming_message'} holds the parsed message
+which consists of a set of
+   $curproc->{'incoming_message'}->{ header }
+and
+   $curproc->{'incoming_message'}->{ body }
+.
+The C<header> is C<FML::Header> object.
+The C<body> is C<MailingList::Messages> object.
+
+=cut
+
+# Descriptions: parse the message to a set of header and body
+#    Arguments: $self $args
+# Side Effects: $curproc->{'incoming_message'} is set up
+# Return Value: none
 sub parse_incoming_message
 {
     my ($curproc, $args) = @_;
@@ -256,4 +404,23 @@ sub parse_incoming_message
 }
 
 
+=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::Kernel appeared in fml5 mailing list driver package.
+See C<http://www.fml.org/> for more details.
+
+=cut
+
+
 1;