fix comments

2 files changed, 60 insertions, 24 deletions

diff --git a/fml/lib/FML/Command.pm b/fml/lib/FML/Command.pm
index 38263430..579b1633 100644
--- a/fml/lib/FML/Command.pm
+++ b/fml/lib/FML/Command.pm
@@ -4,9 +4,14 @@
 #   All rights reserved. This program is free software; you can
 #   redistribute it and/or modify it under the same terms as Perl itself.
 #
-# $FML: Command.pm,v 1.32 2002/09/11 23:18:01 fukachan Exp $
+# $FML: Command.pm,v 1.33 2002/09/22 14:56:39 fukachan Exp $
 #
 
+# XXX 
+# XXX FML::Command should be simple since all program uses this wrapper.
+# XXX So, complicated checks are moved to FML::Process::* and each module.
+# XXX 
+
 package FML::Command;
 use strict;
 use vars qw(@ISA @EXPORT @EXPORT_OK $AUTOLOAD);
@@ -28,20 +33,20 @@ FML::Command - fml command dispatcher
 
 C<FML::Command> is a wrapper and dispathcer for fml commands.
 AUTOLOAD() picks up the command request and dispatches
-C<FML::Command::User::somoting> suitable for the request.
-Also, C<FML::Command::Admin::somoting> for the admin command request
-and makefml commands.
+C<FML::Command::User::something> suitable for the request.
+Also, it kicks off C<FML::Command::Admin::something> for the admin
+command request and makefml commands.
 
 =head1 METHODS
 
 =head2 C<new()>
 
-ordinary constructor.
+constructor.
 
 =cut
 
 
-# Descriptions: ordinary constructor
+# Descriptions: constructor.
 #    Arguments: OBJ($self)
 # Side Effects: none
 # Return Value: OBJ
@@ -54,7 +59,7 @@ sub new
 }
 
 
-# Descriptions: ordinary destructor
+# Descriptions: destructor (dummy).
 #    Arguments: none
 # Side Effects: none
 # Return Value: none
@@ -68,6 +73,9 @@ $rbuf is rewritten as a result.
 For example, this function is used to hide the password in the $rbuf
 buffer.
 
+Each module such as C<FML::Command::$MODE::$SOMETING> specifies
+how to rewrite by rewrite_prompt() method in it.
+
 =cut
 
 
@@ -99,6 +107,9 @@ sub rewrite_prompt
 
 return addresses to inform for the command reply.
 
+Each module such as C<FML::Command::$MODE::$SOMETING> specifies
+recipients by notice_cc_recipient() method in it.
+
 =cut
 
 
@@ -127,8 +138,8 @@ sub notice_cc_recipient
 =head2 C<AUTOLOAD()>
 
 the command dispatcher.
-It hooks up the C<command> request and loads the module in
-C<FML::Command::command>.
+It hooks up the C<$command> request and loads the module in
+C<FML::Command::$MODE::$command>.
 
 =cut
 
diff --git a/fml/lib/FML/Digest.pm b/fml/lib/FML/Digest.pm
index 186fe63a..2093ab11 100644
--- a/fml/lib/FML/Digest.pm
+++ b/fml/lib/FML/Digest.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: Digest.pm,v 1.3 2002/11/18 13:53:09 fukachan Exp $
+# $FML: Digest.pm,v 1.4 2002/12/10 12:00:47 fukachan Exp $
 #
 
 package FML::Digest;
@@ -13,6 +13,9 @@ use vars qw(@ISA @EXPORT @EXPORT_OK $AUTOLOAD);
 use Carp;
 use FML::Log qw(Log LogWarn LogError);
 
+#
+# XXX-TODO: Currently, fml 8 digest has no granuality like fml 4.
+#
 
 =head1 NAME
 
@@ -26,13 +29,15 @@ FML::Digest - create digest, a subset of articles.
 
 =head2 C<new()>
 
+constructor.
+
 =cut
 
 
-# Descriptions:
+# Descriptions: constructor.
 #    Arguments: OBJ($self) HASH_REF($args)
-# Side Effects:
-# Return Value: none
+# Side Effects: none
+# Return Value: OBJ
 sub new
 {
     my ($self, $curproc) = @_;
@@ -43,18 +48,35 @@ sub new
 }
 
 
-# Descriptions: return the last article id sent back as digest
+=head1 GIANT LOCK VERSION of DIGEST 
+
+=head2 id()
+
+same as get_digest_id().
+
+=head2 get_digest_id()
+
+return the last article id sent back as digest.
+
+=head2 set_digest_id()
+
+set the last article id sent back as digest.
+
+=cut
+
+
+# Descriptions: return the last article id sent back as digest.
 #    Arguments: OBJ($self)
 # Side Effects: none
 # Return Value: NUM
 sub id
 {
     my ($self) = @_;
-    $self->digest_id();
+    $self->get_digest_id();
 }
 
 
-# Descriptions: return the last article id sent back as digest
+# Descriptions: return the last article id sent back as digest.
 #    Arguments: OBJ($self)
 # Side Effects: none
 # Return Value: NUM
@@ -92,10 +114,11 @@ sub _get_id
 {
     my ($self, $seq_file) = @_;
 
-    # XXX we should enhance IO::Adapter module to handle
-    # XXX sequential number.
+    # XXX-TODO: we should enhance IO::Adapter module to handle
+    # XXX-TODO: sequential number.
     use File::Sequence;
 
+    # XXX-TODO: defined() check for $sfh.
     if (-f $seq_file) {
 	my $sfh = new File::Sequence { sequence_file => $seq_file };
 	my $id  = $sfh->get_id();
@@ -106,6 +129,7 @@ sub _get_id
     else {
 	Log("$seq_file not found") if 0;
 
+	# XXX-TODO: defined() check for $sfh.
 	my $sfh = new File::Sequence { sequence_file => $seq_file };
 	my $id  = $sfh->increment_id();
 	if ($sfh->error) { LogError( $sfh->error ); }
@@ -115,8 +139,8 @@ sub _get_id
 }
 
 
-# Descriptions: return the last article id sent back as digest
-#    Arguments: OBJ($self)
+# Descriptions: return the last article id sent back as digest.
+#    Arguments: OBJ($self) NUM($id)
 # Side Effects: none
 # Return Value: NUM
 sub set_digest_id
@@ -126,8 +150,9 @@ sub set_digest_id
     my $config   = $curproc->{ config };
     my $seq_file = $config->{ digest_sequence_file };
 
-    # XXX we should enhance IO::Adapter module to handle
-    # XXX sequential number.
+    # XXX-TODO: we should enhance IO::Adapter module to handle
+    # XXX-TODO: sequential number.
+    # XXX-TODO: defined() check for $sfh.
     use File::Sequence;
     my $sfh = new File::Sequence { sequence_file => $seq_file };
     $sfh->set_id($id);
@@ -137,9 +162,9 @@ sub set_digest_id
 }
 
 
-# Descriptions:
+# Descriptions: insert articles sent as digest into reply message queue.
 #    Arguments: OBJ($self) HASH_REF($optargs)
-# Side Effects:
+# Side Effects: update reply messages chain on memory
 # Return Value: none
 sub create_multipart_message
 {