update/fix comments

3 files changed, 78 insertions, 26 deletions

diff --git a/fml/lib/FML/Process/Debug.pm b/fml/lib/FML/Process/Debug.pm
index 76f93875..20f70e60 100644
--- a/fml/lib/FML/Process/Debug.pm
+++ b/fml/lib/FML/Process/Debug.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: Debug.pm,v 1.5 2003/11/16 11:50:57 fukachan Exp $
+# $FML: Debug.pm,v 1.6 2003/11/29 06:35:59 fukachan Exp $
 #
 
 package FML::Process::Debug;
@@ -14,12 +14,43 @@ use Carp;
 
 =head1 NAME
 
-FML::Process::Debug - debug tool
+FML::Process::Debug - debug tool / tiny FML::Process emulator
 
 =head1 SYNOPSIS
 
+    if ($0 eq __FILE__) {
+	my $domain  = "nuinui.net";
+	my $prefix  = "/tmp/nuinui.net";
+	my $map     = "/etc/fml/ml_home_prefix";
+
+	use FML::Process::Debug;
+	my $curproc = new FML::Process::Debug;
+	$curproc->{ config } = { fml_primary_ml_home_prefix_map => $map };
+
+        # special debug flag on
+	$debug = 101;
+	$|     = 1;
+
+	my $ml_home_prefix = new FML::ML::HomePrefix $curproc;
+
+	print "\n# add { $domain => $prefix }\n";
+	$ml_home_prefix->add($domain, $prefix);
+	system "cat $map";
+
+	print "\n# delete { $domain => $prefix }\n";
+	$ml_home_prefix->delete($domain);
+	system "cat $map";
+    }
+
+
 =head1 DESCRIPTION
 
+FML::Pcoess::Debug provides tiny FML::Process:: process emulator for
+debug use.
+
+It also provides dump_curproc() method to dump out $curproc structure
+as string for documentation.
+
 =head1 METHODS
 
 =head2 new()
@@ -61,7 +92,7 @@ simplified version of FML::Process::* only used for debug.
 =cut
 
 
-# Descriptions: create directory $dir if needed
+# Descriptions: create directory $dir if needed.
 #    Arguments: OBJ($self) STR($dir) STR($mode)
 # Side Effects: create directory $dir
 # Return Value: NUM(1 or 0)
@@ -74,7 +105,7 @@ sub mkdir
 }
 
 
-# Descriptions: log message
+# Descriptions: log message.
 #    Arguments: OBJ($self) STR($msg) HASH_REF($msg_args)
 # Side Effects: none
 # Return Value: none
@@ -85,7 +116,7 @@ sub log
 }
 
 
-# Descriptions: log message
+# Descriptions: log message at level as warning.
 #    Arguments: OBJ($self) STR($msg) HASH_REF($msg_args)
 # Side Effects: none
 # Return Value: none
@@ -96,7 +127,7 @@ sub logwarn
 }
 
 
-# Descriptions: log message
+# Descriptions: log message at level as critical error.
 #    Arguments: OBJ($self) STR($msg) HASH_REF($msg_args)
 # Side Effects: none
 # Return Value: none
@@ -151,6 +182,7 @@ return config object.
 sub config
 {
     my ($self) = @_;
+
     return( defined $self->{ config } ? $self->{ config } : undef );
 }
 
diff --git a/fml/lib/FML/Process/Fake.pm b/fml/lib/FML/Process/Fake.pm
index f491c11d..38747724 100644
--- a/fml/lib/FML/Process/Fake.pm
+++ b/fml/lib/FML/Process/Fake.pm
@@ -3,7 +3,7 @@
 # Copyright (C) 2003,2004 Ken'ichi Fukamachi
 #          All rights reserved.
 #
-# $FML: Fake.pm,v 1.4 2004/01/02 02:11:27 fukachan Exp $
+# $FML: Fake.pm,v 1.5 2004/01/02 14:50:35 fukachan Exp $
 #
 
 package FML::Process::Fake;
@@ -43,11 +43,12 @@ It make a C<FML::Process::Kernel> object and return it.
 
 =head2 prepare($args)
 
-load config files and fix @INC.
+load default config files,
+set up domain we need to fake,
+and
+fix @INC if needed.
 
-=head2 verify_request($args)
-
-dummy.
+lastly, parse incoming message input from \*STDIN channel.
 
 =cut
 
@@ -85,6 +86,16 @@ sub prepare
 }
 
 
+=head2 verify_request($args)
+
+parse the header of incoming message to check to: and cc: fields.
+
+If one of them matches the domain to fake, we need to start emulate
+something in run() method running phase.
+
+=cut
+
+
 # Descriptions: verify requests.
 #    Arguments: OBJ($curproc) HASH_REF($args)
 # Side Effects: exit ASAP.
@@ -109,12 +120,6 @@ sub verify_request
 
 the top level dispatcher for C<faker>.
 
-It kicks off C<_faker($args)> for faker.
-
-NOTE:
-C<$args> is passed from parrent libexec/loader.
-See <FML::Process::Switch()> on C<$args> for more details.
-
 =cut
 
 
@@ -129,7 +134,14 @@ sub run
 }
 
 
-# Descriptions: dummy
+=head2 finish($args)
+
+dummy.
+
+=cut
+
+
+# Descriptions: dummy.
 #    Arguments: OBJ($curproc) HASH_REF($args)
 # Side Effects: none
 # Return Value: none
@@ -179,12 +191,12 @@ _EOF_
 }
 
 
-=head1 FAKER FUNCTIONS
+=head1 INTERNAL FAKER FUNCTIONS
 
 =cut
 
 
-# Descriptions: initialize the faker process
+# Descriptions: initialize the faker process.
 #    Arguments: OBJ($curproc) HASH_REF($args)
 # Side Effects: none
 # Return Value: none
@@ -197,7 +209,9 @@ sub _faker_init
     my $faker_domain     = $argv->[0];
     $faker_domain        =~ s/^\@//;
 
-    # anyway chdir(2) before actions.
+    # XXX-TODO: we should chdir(ml_home_prefix of $faker_domain).
+    # anyway chdir(2) to the default domain's ml_home_prefix before
+    # actions for emergency logging.
     chdir $work_dir || exit(1);
 
     my $ml_home_dir  = File::Spec->catfile($work_dir, 'faker');
@@ -214,9 +228,12 @@ sub _faker_init
     $curproc->scheduler_init();
     $curproc->log_message_init();
 
+    # XXX-TODO: hmm, good syntax ???
+    # XXX-TODO: $curproc->is_valid_domain_syntax($faker_domain) ...
+    # XXX-TODO: $domain->valid() style is better?
     # we assume
     # VIRTUAL  @domain faker=domain@${default_domain}
-    # ALIAS    faker=domain: "|/usr/local/libexec/fml/faker domain"
+    # ALIAS    faker=domain: "|/usr/local/libexec/fml/faker @domain"
     if ($curproc->is_valid_domain_syntax($faker_domain)) {
 	$curproc->set_emul_domain($faker_domain);
     }
diff --git a/fml/lib/FML/Process/Flow.pm b/fml/lib/FML/Process/Flow.pm
index 20549866..5015b676 100644
--- a/fml/lib/FML/Process/Flow.pm
+++ b/fml/lib/FML/Process/Flow.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: Flow.pm,v 1.23 2003/09/14 04:05:46 fukachan Exp $
+# $FML: Flow.pm,v 1.24 2004/01/02 14:42:44 fukachan Exp $
 #
 
 package FML::Process::Flow;
@@ -22,7 +22,7 @@ FML::Process::Flow - the process flow
    FML::Process::Flow::ProcessStart($obj, $args);
 
 where C<$obj> is an FML::Process::C<something> object and
-C<$args> is HASH REFERENCE.
+C<$args> is HASH REFERENCE prepared by C<FML::Process::Switch>.
 
 =head1 DESCRIPTION
 
@@ -82,12 +82,14 @@ sub ProcessStart
     # XXX private method to show help ASAP
     # XXX we need to trap here since $process object is clarified after
     # XXX $pkg->new() above.
+    # XXX-TODO: we should not cross _*() private methods over modules.
     $process->_trap_help($args);
 
     # e.g. parse the incoming message (e.g. STDIN)
     $process->prepare($args);
 
     # close and reopen STDERR to record log messages written into STDERR.
+    # XXX-TODO: we should not cross _*() private methods over modules.
     $process->_reopen_stderr_channel();
 
     # validate the request, for example,
@@ -98,13 +100,14 @@ sub ProcessStart
     # start main transaction
     $process->run($args);
 
-    # closing the process
+    # start closing of this process
     $process->finish($args);
 
     # flush stderr channel log.
+    # XXX-TODO: we should not cross _*() private methods over modules.
     $process->_finalize_stderr_channel($args);
 
-    # clean up tmporary files
+    # clean up temporary files
     $process->clean_up_tmpfiles();
 
     # debug