update comments

4 files changed, 158 insertions, 26 deletions

diff --git a/fml/lib/FML/Confirm.pm b/fml/lib/FML/Confirm.pm
index ac8653c9..05f92b06 100644
--- a/fml/lib/FML/Confirm.pm
+++ b/fml/lib/FML/Confirm.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: @template.pm,v 1.1 2001/08/07 12:23:48 fukachan Exp $
+# $FML: Confirm.pm,v 1.1 2001/10/11 23:57:38 fukachan Exp $
 #
 
 package FML::Confirm;
@@ -14,12 +14,30 @@ use Carp;
 
 =head1 NAME
 
-FML::Confirm - assign id for e.g. confirmation 
+FML::Confirm - manipulate confirmation database
 
 =head1 SYNOPSIS
 
+    use FML::Confirm;
+    my $confirm = new FML::Confirm {
+            keyword   => $keyword,
+            cache_dir => $cache_dir,
+            class     => 'subscribe',
+            address   => $address,
+            buffer    => $command,
+        };
+    my $id = $confirm->assign_id;
+    $curproc->reply_message_nl('command.confirm');
+    $curproc->reply_message("\n$id\n");
+
 =head1 DESCRIPTION
 
+This module provides several utilitiy functions for confirmation.
+    assign id
+    store id
+    expire id
+    database manipulation
+
 =head1 METHODS
 
 =head2 C<new($args)>
@@ -27,6 +45,7 @@ FML::Confirm - assign id for e.g. confirmation
 usual constructor.
 
     $args = {
+	keyword   => "confirm",
 	cache_dir => "/some/where",
 	class     => "subscribe",
 	address   => "mail@address",
@@ -35,6 +54,11 @@ usual constructor.
 
 =cut
 
+
+# Descriptions: constructor.
+#    Arguments: OBJ($self) HASH_REF($args)
+# Side Effects: create object
+# Return Value: OBJ
 sub new
 {
     my ($self, $args) = @_;
@@ -51,6 +75,17 @@ sub new
 }
 
 
+=head2 assign_id()
+
+assing new id for current object.
+
+=cut
+
+
+# Descriptions: assing new id for current object
+#    Arguments: OBJ($self)
+# Side Effects: update databse
+# Return Value: STR
 sub assign_id
 {
     my ($self) = @_;
@@ -74,6 +109,10 @@ sub assign_id
 }
 
 
+# Descriptions: open databse
+#    Arguments: OBJ($self) STR($id) STR($comment)
+# Side Effects: open database, mkdir if needed
+# Return Value: HASH_REF to dabase
 sub _open_db
 {
     my ($self, $id, $comment) = @_;
@@ -85,7 +124,7 @@ sub _open_db
     my $dir       = File::Spec->catfile($cache_dir, $class);
 
     unless (-d $dir) {
-	use File::Utils qw(mkdirhier);
+	eval q{ use File::Utils qw(mkdirhier);};
 	mkdirhier($dir, 0700);
     }
 
@@ -98,6 +137,10 @@ sub _open_db
 }
 
 
+# Descriptions: close database
+#    Arguments: OBJ($self)
+# Side Effects: none
+# Return Value: none
 sub _close_db
 {
     my ($self) = @_;
@@ -106,6 +149,17 @@ sub _close_db
 }
 
 
+=head2 store_id($id, $comment)
+
+save id into databse with comment if specified.
+
+=cut
+
+
+# Descriptions: save id into databse
+#    Arguments: OBJ($self) STR($id) STR($comment)
+# Side Effects: update database
+# Return Value: none
 sub store_id
 {    
     my ($self, $id, $comment) = @_;
@@ -121,6 +175,17 @@ sub store_id
 }
 
 
+=head2 find($id)
+
+find database value for $id
+
+=cut
+
+
+# Descriptions: find value for $id
+#    Arguments: OBJ($self) STR($id)
+# Side Effects: update object
+# Return Value: STR
 sub find
 {
     my ($self, $id) = @_;    
@@ -135,6 +200,17 @@ sub find
 }
 
 
+=head2 get_request($id)
+
+get value for request id $id.
+
+=cut
+
+
+# Descriptions: get request id
+#    Arguments: OBJ($self) STR($id)
+# Side Effects: none
+# Return Value: STR
 sub get_request
 {
     my ($self, $id) = @_;    
@@ -147,6 +223,17 @@ sub get_request
 }
 
 
+=head2 get_address($id)
+
+get address for $id.
+
+=cut 
+
+
+# Descriptions: get address for $id
+#    Arguments: OBJ($self) STR($id)
+# Side Effects: none
+# Return Value: STR
 sub get_address
 {
     my ($self, $id) = @_;    
@@ -159,6 +246,18 @@ sub get_address
 }
 
 
+=head2 is_expired($found, $howold)
+
+request for $id is expired or not.
+specify $found (database value) for $it as argument.
+
+=cut
+
+
+# Descriptions: request for $id is expired or not
+#    Arguments: OBJ($self) STR($found) NUM($howold)
+# Side Effects: none
+# Return Value: 1 or 0
 sub is_expired
 {
     my ($self, $found, $howold) = @_;
diff --git a/fml/lib/FML/Credential.pm b/fml/lib/FML/Credential.pm
index b74bb053..9581bb2c 100644
--- a/fml/lib/FML/Credential.pm
+++ b/fml/lib/FML/Credential.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: Credential.pm,v 1.16 2001/10/10 14:56:59 fukachan Exp $
+# $FML: Credential.pm,v 1.17 2001/10/13 03:03:43 fukachan Exp $
 #
 
 package FML::Credential;
@@ -42,7 +42,7 @@ bind \%Credential to $self and return it as an object.
 # Descriptions: usual constructor
 #               bind $self ($me) to \%Credential, so
 #               you can access the same \%Credential through this object.
-#    Arguments: $self
+#    Arguments: OBJ($self)
 # Side Effects: bind $self ($me) to \%Credential
 # Return Value: object
 sub new
@@ -63,8 +63,9 @@ sub DESTROY {}
 
 =head2 C<is_same_address($addr1, $addr2 [, $level])>
 
-return 1 if C<$addr1> and C<$addr2> looks same within some ambiguity.
-The ambiguity is followed by these rules.
+return 1 (same ) or 0 (different).
+It returns 1 if C<$addr1> and C<$addr2> looks same within some
+ambiguity.  The ambiguity is defined by the following rules:
 
 1. C<user> part must be the same case sensitively.
 
@@ -78,8 +79,8 @@ The ambiguity is followed by these rules.
          c.d.jp
            ......
 
-By default we compare the last 3 level. 
-For example, 
+By default we compare the last (top) C<3> level. 
+For example, consider these two addresses:
 
             rudo@nuinui.net   
             rudo@sapporo.nuinui.net
@@ -94,6 +95,10 @@ are same since the last 3 top level domains are same.
 =cut
 
 
+# Descriptions: compare addresses are same.
+#    Arguments: OBJ($self) STR($xaddr) STR($xaddr) NUM($max_level)
+# Side Effects: none
+# Return Value: 1 or 0
 sub is_same_address
 {
     my ($self, $xaddr, $yaddr, $max_level) = @_;
@@ -132,10 +137,10 @@ return 0 if not.
 =cut
 
 
-# Descriptions: 
-#    Arguments: $self $curproc $args
-# Side Effects: 
-# Return Value: none
+# Descriptions: sender of the current process is an ML member or not.
+#    Arguments: OBJ($self) OBJ($curproc) HASH_REF($args)
+# Side Effects: none
+# Return Value: 1 or 0
 sub is_member
 {
     my ($self, $curproc, $args) = @_;
@@ -166,6 +171,11 @@ sub is_member
 }
 
 
+# Descriptions: $map contains $address or not in some ambiguity
+#               by is_same_address().
+#    Arguments: OBJ($self) STR($map) STR($address)
+# Side Effects: none
+# Return Value: 1 or 0
 sub has_address_in_map
 {
     my ($self, $map, $address) = @_;
@@ -211,6 +221,10 @@ The system accounts are given as
 =cut
 
 
+# Descriptions: sender of this process is a system account ?
+#    Arguments: OBJ($self) OBJ($curproc) HASH_REF($args)
+# Side Effects: none
+# Return Value: STR
 sub match_system_accounts
 {
     my ($self, $curproc, $args) = @_;
@@ -237,7 +251,7 @@ process.
 =cut
 
 # Descriptions: returh the mail sender
-#    Arguments: $self
+#    Arguments: OBJ($self)
 # Side Effects: none
 # Return Value: mail address
 sub sender
@@ -260,6 +274,10 @@ return the number of C<level>.
 =cut
 
 
+# Descriptions: set address comparison level
+#    Arguments: OBJ($self) NUM($level)
+# Side Effects: change private variables in object
+# Return Value: NUM
 sub set_compare_level
 {
     my ($self, $level) = @_;
@@ -267,9 +285,13 @@ sub set_compare_level
 }
 
 
+# Descriptions: return address comparison level
+#    Arguments: OBJ($self)
+# Side Effects: none
+# Return Value: NUM
 sub get_compare_level
 {
-    my ($self, $level) = @_;
+    my ($self) = @_;
     return (defined $self->{ _max_level } ? $self->{ _max_level } : undef);
 }
 
@@ -286,10 +308,10 @@ sub get_compare_level
 =cut
 
 
-# Descriptions: 
-#    Arguments: $self key
-# Side Effects: none
-# Return Value: string
+# Descriptions: get value for the specified key
+#    Arguments: OBJ($self) STR($key)
+# Side Effects: change object
+# Return Value: STR
 sub get
 {
     my ($self, $key) = @_;
@@ -297,10 +319,10 @@ sub get
 }
 
 
-# Descriptions: 
-#    Arguments: $self key value
+# Descriptions: set value for $key to be $value
+#    Arguments: OBJ($self) STR($key) STR($value)
 # Side Effects: none
-# Return Value: string
+# Return Value: STR
 sub set
 {
     my ($self, $key, $value) = @_;
diff --git a/fml/lib/FML/PCB.pm b/fml/lib/FML/PCB.pm
index 2593cc6f..2dbd0ab1 100644
--- a/fml/lib/FML/PCB.pm
+++ b/fml/lib/FML/PCB.pm
@@ -1,7 +1,10 @@
 #-*- perl -*-
-# Copyright (C) 2000,2001 Ken'ichi Fukamachi
 #
-# $FML: PCB.pm,v 1.5 2001/04/03 09:45:40 fukachan Exp $ 
+#  Copyright (C) 2000,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. 
+#
+# $FML$
 #
 
 package FML::PCB;
diff --git a/fml/lib/FML/Parse.pm b/fml/lib/FML/Parse.pm
index 37f84cc3..4f3bf4fe 100644
--- a/fml/lib/FML/Parse.pm
+++ b/fml/lib/FML/Parse.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: Parse.pm,v 1.15 2001/05/05 15:41:43 fukachan Exp $
+# $FML: Parse.pm,v 1.16 2001/05/27 14:27:54 fukachan Exp $
 #
 
 package FML::Parse;
@@ -46,6 +46,11 @@ Normally C<fd> is the handle for STDIN channel.
 
 =cut
 
+
+# Descriptions: parse message read from file handle $fd
+#    Arguments: OBJ($self) OBJ($curproc) HANDLE($fd)
+# Side Effects: none
+# Return Value: OBJ
 sub new
 {
     my ($self, $curproc, $fd) = @_;
@@ -57,7 +62,10 @@ sub new
 }
 
 
-# return ( $ref_to_mail_header, $ref_to_mail_body, $error_code);
+# Descriptions: parse message read from file handle $fd
+#    Arguments: OBJ($self) HASH_REF($args)
+# Side Effects: none
+# Return Value: OBJ
 sub _parse
 {
     my ($self, $curproc, $fd) = @_;