update comments, copyright

2 files changed, 103 insertions, 29 deletions

diff --git a/fml/lib/Mail/Delivery/Queue.pm b/fml/lib/Mail/Delivery/Queue.pm
index 9c146783..44414a08 100644
--- a/fml/lib/Mail/Delivery/Queue.pm
+++ b/fml/lib/Mail/Delivery/Queue.pm
@@ -1,10 +1,10 @@
 #-*- perl -*-
 #
-#  Copyright (C) 2001 Ken'ichi Fukamachi
+#  Copyright (C) 2001,2002 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: Queue.pm,v 1.6 2001/08/24 00:15:49 fukachan Exp $
+# $FML: Queue.pm,v 1.7 2001/12/22 09:21:17 fukachan Exp $
 #
 
 package Mail::Delivery::Queue;
@@ -72,6 +72,10 @@ C<new()> assigns them but do no actual works.
 =cut
 
 
+# Descriptions: constructor.
+#    Arguments: OBJ($self) HASH_REF($args)
+# Side Effects: initialize object
+# Return Value: OBJ
 sub new
 {
     my ($self, $args) = @_;
@@ -100,14 +104,24 @@ sub new
 }
 
 
+# Descriptions: mkdir recursively
+#    Arguments: STR($dir)
+# Side Effects: none
+# Return Value: ARRAY or UNDEF
 sub _mkdirhier
 {
     my ($dir) = @_;
-    use File::Path;
-    mkpath( [ $dir ], 0, 0755);
+    eval q{
+	use File::Path;
+	mkpath( [ $dir ], 0, 0755);
+    };
 }
 
 
+# Descriptions: return new queue identifier
+#    Arguments: none
+# Side Effects: increment counter $Counter
+# Return Value: STR
 sub _new_queue_id
 {
     $Counter++;
@@ -121,6 +135,11 @@ return the queue id assigned to the object C<$self>.
 
 =cut
 
+
+# Descriptions: return object identifier (queue id)
+#    Arguments: OBJ($self)
+# Side Effects: none
+# Return Value: STR
 sub id
 {
     my ($self) = @_;
@@ -134,6 +153,11 @@ return the file name of the queue id assigned to the object C<$self>.
 
 =cut
 
+
+# Descriptions: return queue file name assigned to this object
+#    Arguments: OBJ($self)
+# Side Effects: none
+# Return Value: STR
 sub filename
 {
     my ($self) = @_;
@@ -155,6 +179,11 @@ where C<$qid> is like this: 990157187.20792.1
 
 =cut
 
+
+# Descriptions: return queue file list 
+#    Arguments: OBJ($self)
+# Side Effects: none
+# Return Value: HASH_ARRAY
 sub list
 {
     my ($self) = @_;
@@ -188,6 +217,11 @@ The returned information is
 
 =cut
 
+
+# Descriptions: get information of queue for this object
+#    Arguments: OBJ($self) STR($id)
+# Side Effects: none
+# Return Value: HASH_REF
 sub getidinfo
 {
     my ($self, $id) = @_;
@@ -242,6 +276,10 @@ sub LOCK_NB {4;}
 sub LOCK_UN {8;}
 
 
+# Descriptions: lock queue
+#    Arguments: OBJ($self) HASH_REF($args)
+# Side Effects: flock queue
+# Return Value: 1 or 0
 sub lock
 {
     my ($self, $args) = @_;
@@ -259,6 +297,10 @@ sub lock
 }
 
 
+# Descriptions: unlock queue
+#    Arguments: OBJ($self)
+# Side Effects: unlock queue by flock(2)
+# Return Value: 1 or 0
 sub unlock
 {
     my ($self) = @_;
@@ -282,6 +324,11 @@ C<DESTRUCTOR>.
 
 =cut
 
+
+# Descriptions: create a new queue file.
+#    Arguments: OBJ($self) OBJ($msg)
+# Side Effects: none
+# Return Value: 1 or 0
 sub in
 {
     my ($self, $msg) = @_;
@@ -309,6 +356,11 @@ C<info/recipients/> directories.
 
 =cut
 
+
+# Descriptions: set value for key
+#    Arguments: OBJ($self) STR($key) STR($value)
+# Side Effects: none
+# Return Value: same as close()
 sub set
 {
     my ($self, $key, $value) = @_;
@@ -347,7 +399,7 @@ directory to C<active/> directory like C<postfix> queue strategy.
 
 
 # Descriptions: set this object queue to be deliverable
-#    Arguments: $self $args
+#    Arguments: OBJ($self)
 # Side Effects: move $queue_id file from new/ to active/
 # Return Value: 1 (success) or 0 (fail)
 sub setrunnable
@@ -380,6 +432,10 @@ return 1 (valid) or 0.
 =cut
 
 
+# Descriptions: remove queue files for this object (queue)
+#    Arguments: OBJ($self)
+# Side Effects: remove queue file(s)
+# Return Value: none
 sub remove
 {
     my ($self) = @_;
@@ -393,6 +449,10 @@ sub remove
 }
 
 
+# Descriptions: this object (queue) is sane ?
+#    Arguments: OBJ($self)
+# Side Effects: none
+# Return Value: 1 or 0
 sub valid
 {
     my ($self) = @_;
@@ -408,6 +468,10 @@ sub valid
 }
 
 
+# Descriptions: clear this queue file
+#    Arguments: OBJ($self)
+# Side Effects: unlink this queue
+# Return Value: NUM
 sub DESTROY
 {
     my ($self) = @_;
@@ -421,7 +485,7 @@ Ken'ichi Fukamachi
 
 =head1 COPYRIGHT
 
-Copyright (C) 2001 Ken'ichi Fukamachi
+Copyright (C) 2001,2002 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.
diff --git a/fml/lib/Mail/Delivery/SMTP.pm b/fml/lib/Mail/Delivery/SMTP.pm
index abe194e2..3e46ae3f 100644
--- a/fml/lib/Mail/Delivery/SMTP.pm
+++ b/fml/lib/Mail/Delivery/SMTP.pm
@@ -1,10 +1,10 @@
 #-*- perl -*-
 #
-#  Copyright (C) 2000-2001 Ken'ichi Fukamachi
+#  Copyright (C) 2000,2001,2002 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: SMTP.pm,v 1.9 2001/10/10 09:46:21 fukachan Exp $
+# $FML: SMTP.pm,v 1.10 2001/12/22 09:21:17 fukachan Exp $
 #
 
 
@@ -110,10 +110,11 @@ transactions.
 
 =cut
 
+
 # Descriptions: Mail::Delivery::SMTP constructor
-#    Arguments: $self $args
+#    Arguments: OBJ($self) HASH_REF($args)
 # Side Effects: $self ($me) hash has some default values
-# Return Value: object
+# Return Value: OBJ
 sub new
 {
     my ($self, $args) = @_;
@@ -139,7 +140,7 @@ sub new
 
 
 # Descriptions: send a (SMTP/LMTP) command string to BSD socket
-#    Arguments: $self $command_string
+#    Arguments: OBJ($self) STR($command)
 # Side Effects: log file by _smtplog
 #               set _last_command and _error_action in object itself
 # Return Value: none
@@ -162,7 +163,7 @@ sub _send_command
 
 
 # Descriptions: receive a reply for a (SMTP/LMTP) command
-#    Arguments: $self
+#    Arguments: OBJ($self)
 # Side Effects: log file by _smtplog
 # Return Value: none
 sub _read_reply
@@ -241,7 +242,7 @@ sub _read_reply
 #               1. try connect(2) by IPv6 if we can use Socket6.pm
 #               2. try connect(2) by IPv4
 #                  if $host is not IPv6 raw address e.g. [::1]:25
-#    Arguments: $self $args
+#    Arguments: OBJ($self) HASH_REF($args)
 # Side Effects: set file handle (BSD socket) in $self->{_socket}
 # Return Value: file handle (created BSD socket) or undef()
 sub _connect
@@ -279,6 +280,7 @@ sub _connect
     }
 }
 
+
 =head2 C<socket_is_connected($socket)>
 
 $socket has peer or not by C<getpeername()>.
@@ -289,6 +291,10 @@ $socket has peer or not by C<getpeername()>.
 =cut
 
 
+# Descriptions: this socket is connected or not
+#    Arguments: OBJ($self) HANDLE($socket)
+# Side Effects: none
+# Return Value: 1 or 0
 sub socket_is_connected
 {
     my ($self, $socket) = @_;
@@ -308,9 +314,9 @@ close BSD socket
 =cut
 
 # Descriptions: close BSD socket
-#    Arguments: $self
-# Side Effects:
-# Return Value: none
+#    Arguments: OBJ($self)
+# Side Effects: none
+# Return Value: same as close()
 sub close
 {
     my ($self) = @_;
@@ -378,6 +384,7 @@ See L<Mail::Message> for more details.
 
 =cut
 
+
 # Descriptions: main delivery loop for each recipient_maps and each mta.
 #               real delivery is done within _deliver() method.
 #               algorithm:
@@ -388,7 +395,7 @@ See L<Mail::Message> for more details.
 #                    }
 #                 }
 #
-#    Arguments: $self $args
+#    Arguments: OBJ($self) HASH_REF($args)
 # Side Effects: See Mail::Delivery::Utils for recipient_map utilities
 #               to track the delivery process status.
 # Return Value: none
@@ -518,7 +525,7 @@ sub deliver
 #              >250 oK
 #              <QUIT
 #              >221 good bye
-#    Arguments: $self $args
+#    Arguments: OBJ($self) HASH_REF($args)
 # Side Effects: remove error messages when we return from here
 #               for the next _deliver() session.
 # Return Value: none
@@ -583,8 +590,8 @@ sub _deliver
 
 # Descriptions: initialize _deliver() process
 #               this routine is called at the first phase in _deliver()
-#    Arguments: $self $args
-# Side Effects:
+#    Arguments: OBJ($self) HASH_REF($args)
+# Side Effects: initialize object
 # Return Value: none
 sub _initialize_delivery_session
 {
@@ -599,8 +606,9 @@ sub _initialize_delivery_session
 ##### MAIL FROM:
 #####
 
+
 # Descriptions: send SMTP command "MAIL FROM"
-#    Arguments: $self $args
+#    Arguments: OBJ($self) HASH_REF($args)
 # Side Effects: none
 # Return Value: none
 #     See Also: RFC821, RFC1123
@@ -620,6 +628,7 @@ sub _send_mail_from
 ##### RCPT TO:
 #####
 
+
 # Descriptions: We evaluate recipient_maps parameter here.
 #               You can use a lot of classes for this directive: e.g.
 #               file, UNIX's /etc/group, YP, SQL, LDAP, ...
@@ -628,7 +637,7 @@ sub _send_mail_from
 #                                         mysql:toymodel
 #               IO::Adapter class is essential to handle abstract
 #               $recipient_map.
-#    Arguments: $self $args
+#    Arguments: OBJ($self) HASH_REF($args)
 # Side Effects: $self->{ _retry_recipient_table } has recipients which
 #               causes some errors.
 #               _{set,get}_map_position() and _{set,get}_map_status()
@@ -702,7 +711,7 @@ sub _send_recipient_list_by_recipient_map
 
 
 # Descriptions: send "RCPT TO:<recipient>" to MTA
-#    Arguments: $self $args
+#    Arguments: OBJ($self) HASH_REF($args)
 # Side Effects: none
 # Return Value: none
 sub _send_recipient_list
@@ -722,7 +731,7 @@ sub _send_recipient_list
 #####
 
 # Descriptions: send the header part of the message to socket
-#    Arguments: $self $socket $ref_to_header
+#    Arguments: OBJ($self) HANDLE($socket) OBJ($header)
 #               $ref_to_header is the FML::Header class object.
 # Side Effects: none
 # Return Value: none
@@ -739,7 +748,7 @@ sub _send_header_to_mta
 
 
 # Descriptions: send the body part of the message to socket
-#    Arguments: $self $socket "Mail::Message object"
+#    Arguments: OBJ($self) HANDLE($socket) OBJ($msg)
 # Side Effects: none
 # Return Value: none
 sub _send_body_to_mta
@@ -754,8 +763,8 @@ sub _send_body_to_mta
 
 
 # Descriptions: send message itself to file handle (BSD socket here)
-#    Arguments: $self $args
-# Side Effects:
+#    Arguments: OBJ($self) HASH_REF($args)
+# Side Effects: none
 # Return Value: none
 sub _send_data_to_mta
 {
@@ -798,8 +807,9 @@ sub _send_data_to_mta
 ##### QUIT / RSET
 #####
 
+
 # Descriptions: send the SMTP reset "RSET" command
-#    Arguments: $self $args
+#    Arguments: OBJ($self) HASH_REF($args)
 # Side Effects: none
 # Return Value: none
 sub _reset_smtp_transaction
@@ -830,7 +840,7 @@ Ken'ichi Fukamachi
 
 =head1 COPYRIGHT
 
-Copyright (C) 2001 Ken'ichi Fukamachi
+Copyright (C) 2000,2001,2002 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.