update comments, documents

4 files changed, 130 insertions, 46 deletions

diff --git a/fml/lib/FML/Config/Convert.pm b/fml/lib/FML/Config/Convert.pm
index c2e16ea3..6eaa3249 100644
--- a/fml/lib/FML/Config/Convert.pm
+++ b/fml/lib/FML/Config/Convert.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: Convert.pm,v 1.2 2001/12/09 14:52:35 fukachan Exp $
+# $FML: Convert.pm,v 1.3 2001/12/22 09:21:05 fukachan Exp $
 #
 
 
@@ -16,17 +16,48 @@ use Carp;
 
 =head1 NAME
 
-FML::Config::Convert --
+FML::Config::Convert -- variable expansion for __variable__
 
 =head1 SYNOPSIS
 
+    my $in  = new FileHandle $src;
+    my $out = new FileHandle "> $dst.$$";
+
+    if (defined $in && defined $out) {
+        chmod 0644, "$dst.$$";
+
+        &FML::Config::Convert::convert($in, $out, $config);
+
+        $out->close();
+        $in->close();
+
+        rename("$dst.$$", $dst) || croak("fail to rename $dst");
+    }
+    else {
+        croak("fail to open $src") unless defined $in;
+        croak("fail to open $dst") unless defined $out;
+    }
+
 =head1 DESCRIPTION
 
+Installer needs variable expansion. This module provides variable
+expansion for __variable__ style string.
+
 =head1 METHODS
 
+=head2 convert($in, $out, $config)
+
+conversion filter. The source is given by file handle $in,
+output is specified as file handle $out.
+Specify HASH_REF $config as real value.
+
 =cut
 
 
+# Descriptions: conversion filter.
+#    Arguments: HANDLE($in) HANDLE($out) HASH_REF($config)
+# Side Effects: print out to handle $out
+# Return Value: none
 sub convert
 {
    my ($in, $out, $config) = @_;
@@ -43,6 +74,10 @@ sub convert
 }
 
 
+# Descriptions: replace __variable__ with real value in $config
+#    Arguments: STR($buf) HASH_REF($config)
+# Side Effects: buffer replacement
+# Return Value: STR($buf)
 sub _replace
 {
     my ($buf, $config) = @_;
diff --git a/fml/lib/FML/Process/Command.pm b/fml/lib/FML/Process/Command.pm
index 95795fc6..35c203a1 100644
--- a/fml/lib/FML/Process/Command.pm
+++ b/fml/lib/FML/Process/Command.pm
@@ -3,7 +3,7 @@
 # Copyright (C) 2000,2001 Ken'ichi Fukamachi
 #          All rights reserved.
 #
-# $FML: Command.pm,v 1.24 2001/11/27 11:40:30 fukachan Exp $
+# $FML: Command.pm,v 1.25 2001/12/22 09:21:08 fukachan Exp $
 #
 
 package FML::Process::Command;
@@ -21,7 +21,7 @@ use FML::Config;
 
 =head1 NAME
 
-FML::Process::Command -- fml5 command dispacher.
+FML::Process::Command -- command dispacher.
 
 =head1 SYNOPSIS
 
@@ -35,24 +35,24 @@ See L<FML::Process::Flow> for details of fml process flow.
 C<FML::Process::Command> is a command wrapper and top level
 dispatcher for commands.
 It kicks off corresponding
-C<FML::Command>->C<$command($curproc,$args)>
+
+   FML::Command->$command($curproc, $command_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.
+make fml process object, which inherits C<FML::Process::Kernel>.
 
 =cut
 
 
+# Descriptions: standard constructor.
+#    Arguments: OBJ($self) HASH_REF($args)
+# Side Effects: inherit FML::Process::Kernel
+# Return Value: OBJ
 sub new
 {
     my ($self, $args) = @_;
@@ -62,6 +62,16 @@ sub new
 }
 
 
+=head2 C<prepare($args)>
+
+forward the request to SUPER CLASS.
+
+=cut
+
+# Descriptions: dummy
+#    Arguments: OBJ($self) HASH_REF($args)
+# Side Effects: none
+# Return Value: none
 sub prepare
 {
     my ($self, $args) = @_;
@@ -75,6 +85,11 @@ verify the sender is a valid member or not.
 
 =cut
 
+
+# Descriptions: verify the sender of this process is an ML member.
+#    Arguments: OBJ($self) HASH_REF($args)
+# Side Effects: none
+# Return Value: 1 or 0
 sub verify_request
 {
     my ($curproc, $args) = @_;
@@ -85,7 +100,7 @@ sub verify_request
 =head2 C<run($args)>
 
 dispatcher to run correspondig C<FML::Command::command> for
-C<command>.
+C<command>. Standard style follows:
 
     lock
     execute FML::Command::command
@@ -93,6 +108,11 @@ C<command>.
 
 =cut
 
+
+# Descriptions: call _evaluate_command()
+#    Arguments: OBJ($self) HASH_REF($args)
+# Side Effects: none
+# Return Value: none
 sub run
 {
     my ($curproc, $args) = @_;
@@ -102,6 +122,8 @@ sub run
 
 =head2 help()
 
+show help.
+
 =cut
 
 
@@ -128,6 +150,12 @@ _EOF_
 
 =cut
 
+
+# Descriptions: finalize command process.
+#               reply messages, command results et. al.
+#    Arguments: OBJ($self) HASH_REF($args)
+# Side Effects: queue manipulation
+# Return Value: none
 sub finish
 {
     my ($curproc, $args) = @_;
@@ -137,6 +165,11 @@ sub finish
 }
 
 
+# Descriptions: check message of the current process
+#               whether it contais keyword e.g. "confirm".
+#    Arguments: OBJ($self) STR_REF($ra_body)
+# Side Effects: none
+# Return Value: STR or 0
 sub _pre_scan
 {
     my ($curproc, $ra_body) = @_;
@@ -154,6 +187,11 @@ sub _pre_scan
 }
 
 
+# Descriptions: check command (specified in $opts) content:
+#               syntax check, permission of command use et. al.
+#    Arguments: OBJ($self) HASH_REF($args) HASH_REF($opts)
+# Side Effects: none
+# Return Value: 1 or 0
 sub _can_accpet_command
 {
     my ($curproc, $args, $opts) = @_;
@@ -201,9 +239,9 @@ sub _can_accpet_command
 
 # Descriptions: parse command buffer to make
 #               argument vector after command name
-#    Arguments: ($string_to_parse, $string_command_name)
+#    Arguments: STR($command) STR($comname)
 # Side Effects: none
-# Return Value: ARRAY REFERENCE
+# Return Value: HASH_ARRAY
 sub _parse_command_options
 {
     my ($command, $comname) = @_;
@@ -219,6 +257,10 @@ sub _parse_command_options
 }
 
 
+# Descriptions: return command name ( ^\S+ in $command )
+#    Arguments: STR($command)
+# Side Effects: none
+# Return Value: STR
 sub _get_command_name
 {
     my ($command) = @_;
@@ -227,8 +269,13 @@ sub _get_command_name
 }
 
 
-# dynamic loading of command definition.
-# It resolves your customized command easily.
+# Descriptions: scan message body and execute approviate command
+#               with dynamic loading of command definition.
+#               It resolves your customized command easily.
+#    Arguments: OBJ($self) HASH_REF($args)
+# Side Effects: loading FML::Command::command.
+#               prepare messages to return.
+# Return Value: none
 sub _evaluate_command
 {
     my ($curproc, $args) = @_;
diff --git a/fml/lib/FML/Process/ConfViewer.pm b/fml/lib/FML/Process/ConfViewer.pm
index daf78617..bb5d87a1 100644
--- a/fml/lib/FML/Process/ConfViewer.pm
+++ b/fml/lib/FML/Process/ConfViewer.pm
@@ -3,7 +3,7 @@
 # Copyright (C) 2000,2001 Ken'ichi Fukamachi
 #          All rights reserved.
 #
-# $FML: ConfViewer.pm,v 1.5 2001/11/27 15:56:55 fukachan Exp $
+# $FML: ConfViewer.pm,v 1.6 2001/12/22 09:21:09 fukachan Exp $
 #
 
 package FML::Process::ConfViewer;
@@ -57,16 +57,17 @@ sub new
 }
 
 
-# Descriptions: dummy yet now
+# Descriptions: dummy
 #    Arguments: OBJ($self) HASH_REF($args)
 # Side Effects: none
 # Return Value: none
 sub prepare { ; }
 
 
-# Descriptions: check @ARGV
+# Descriptions: check @ARGV, call help() if needed
 #    Arguments: OBJ($self) HASH_REF($args)
-# Side Effects: longjmp() to help() if appropriate
+# Side Effects: exit ASAP.
+#               longjmp() to help() if appropriate
 # Return Value: none
 sub verify_request
 {
@@ -96,7 +97,7 @@ See <FML::Process::Switch()> on C<$args> for more details.
 =cut
 
 
-# Descriptions: just a switch
+# Descriptions: just a switch, call _fmlconf()
 #    Arguments: OBJ($self) HASH_REF($args)
 # Side Effects: none
 # Return Value: none
@@ -113,6 +114,8 @@ sub run
 
 =head2 help()
 
+show help.
+
 =cut
 
 
@@ -137,7 +140,7 @@ _EOF_
 }
 
 
-# Descriptions: dummy yet now
+# Descriptions: dummy
 #    Arguments: OBJ($self) HASH_REF($args)
 # Side Effects: none
 # Return Value: none
@@ -151,7 +154,7 @@ run dump_variables of C<FML::Config>.
 =cut
 
 
-# Descriptions: show configurations variables in the sytle "key = value"
+# Descriptions: show configurations variables in the sytle "key = value".
 #    Arguments: OBJ($self) HASH_REF($args)
 # Side Effects: none
 # Return Value: none
diff --git a/fml/lib/FML/Process/Configure.pm b/fml/lib/FML/Process/Configure.pm
index a7e38622..b6ea473c 100644
--- a/fml/lib/FML/Process/Configure.pm
+++ b/fml/lib/FML/Process/Configure.pm
@@ -3,7 +3,7 @@
 # Copyright (C) 2000,2001 Ken'ichi Fukamachi
 #          All rights reserved.
 #
-# $FML: Configure.pm,v 1.33 2001/12/08 14:32:08 fukachan Exp $
+# $FML: Configure.pm,v 1.34 2001/12/22 09:21:09 fukachan Exp $
 #
 
 package FML::Process::Configure;
@@ -21,7 +21,7 @@ use FML::Config;
 
 =head1 NAME
 
-FML::Process::Configure -- fmlconf and makefml main functions
+FML::Process::Configure -- makefml main functions
 
 =head1 SYNOPSIS
 
@@ -31,16 +31,7 @@ FML::Process::Configure -- fmlconf and makefml main functions
 
 =head1 DESCRIPTION
 
-FML::Process::Configure provides the main function for
-C<fmlconf>
- and
-C<makefml>.
-
-These programs,
-C<fmlconf> and C<makefml>,
-bootstrap by using these modules in this order.
-
-   libexec/loader -> FML::Process::Switch -> FML::Process::Configure
+FML::Process::Configure provides the main function for C<makefml>.
 
 See C<FML::Process::Flow> for the flow detail.
 
@@ -59,7 +50,7 @@ dummy.
 
 
 # Descriptions: constructor
-#    Arguments: $self $args
+#    Arguments: OBJ($self) HASH_REF($args)
 # Side Effects: none
 # Return Value: FML::Process::Configure object
 sub new
@@ -71,16 +62,17 @@ sub new
 }
 
 
-# Descriptions: dummy yet now
-#    Arguments: $self $args
+# Descriptions: dummy
+#    Arguments: OBJ($self) HASH_REF($args)
 # Side Effects: none
 # Return Value: none
 sub prepare { ; }
 
 
-# Descriptions: check @ARGV
-#    Arguments: $self $args
-# Side Effects: longjmp() to help() if appropriate
+# Descriptions: check @ARGV, call help() if needed.
+#    Arguments: OBJ($self) HASH_REF($args)
+# Side Effects: exit ASAP.
+#               longjmp() to help() if appropriate
 # Return Value: none
 sub verify_request
 {
@@ -110,8 +102,9 @@ See <FML::Process::Switch()> on C<$args> for more details.
 
 =cut
 
-# Descriptions: just a switch
-#    Arguments: $self $args
+
+# Descriptions: just a switch, call _makefml().
+#    Arguments: OBJ($self) HASH_REF($args)
 # Side Effects: none
 # Return Value: none
 sub run
@@ -125,11 +118,17 @@ sub run
 }
 
 
+# Descriptions: dummy
+#    Arguments: OBJ($self) HASH_REF($args)
+# Side Effects: none
+# Return Value: none
 sub finish { 1;}
 
 
 =head2 help()
 
+show help.
+
 =cut
 
 
@@ -177,8 +176,8 @@ See <FML::Process::Switch()> on C<$args> for more details.
 
 
 # Descriptions: makefml top level dispacher
-#    Arguments: $self $args
-# Side Effects:
+#    Arguments: OBJ($self) HASH_REF($args)
+# Side Effects: load FML::Command::command module and execute it.
 # Return Value: none
 sub _makefml
 {