update POD documents

5 files changed, 324 insertions, 51 deletions

diff --git a/fml/lib/MailingList/Messages.pm b/fml/lib/MailingList/Messages.pm
index dc081af2..557f2611 100644
--- a/fml/lib/MailingList/Messages.pm
+++ b/fml/lib/MailingList/Messages.pm
@@ -30,7 +30,7 @@ sub new
 ######################################################################
 =head1 NAME
 
-MailingList::Messages -- message manipulators
+MailingList::Messages -- message manipulator
 
 =head1 SYNOPSIS
 
@@ -48,23 +48,61 @@ MailingList::Messages -- message manipulators
 =head1 DESCRIPTION
 
 A message has the content and a header including the next message
-pointer, et. al. Out idea is similar to IPv6.
+pointer, et. al. 
 
-Message Format
+The messages are chained from/to others among them.
+Out idea on the chain is similar to IPv6.
+For example, MIME/multipart is a chain of messages such as
 
-   %message = {
-                version      => 1.0
-                content_type => text/plain
+  mesg1 -> mesg2 -> mesg3 (-> undef)
+
+So the message format is as follows. 
+We describe a message as a hash reference.
+
+   $message = {
                 next         => \%next_message
                 prev         => \%prev_message
+
+                version      => 1.0
+                mime_version => 1.0
+                content_type => text/plain
                 header       => {
                                     field_name => field_value
                                  }
                 content      => \$message_body
                }
 
+   key              value
+   -----------------------------------------------------
+   next             pointer to the next message
+   prev             pointer to the previous message
+   version          MailingList::Message object version
+   mime_version     MIME version
+   content_type     MIME content-type
+   header           reference to a header hash
+   content          reference to the content (that is, memory area)
+
+Each default value follows:
+
+   key              value
+   -----------------------------------------------------
+   next             undef
+   prev             undef
+   version          1.0
+   mime_version     1.0
+   content_type     text/plain
+   header           undef
+   content          ''
 
-=item Function()
+=head1 METHOD
+
+=item C<new($args)>
+
+constructor. if $args is given, create() method is called.
+
+=item C<create($args)>
+
+build a template message following the given $args (a hash reference).
 
 =cut
 
@@ -78,7 +116,7 @@ sub create
 
     $self->{ version }      = $args->{ version }       || 1.0; 
     $self->{ mime_version } = $args->{ mime_version }  || 1.0; 
-    $self->{ content_type } = $args->{ content_type  } || 'message/rfc822';
+    $self->{ content_type } = $args->{ content_type  } || 'text/plain';
     $self->{ header  }      = $args->{ header  } || undef;
     $self->{ content }      = $args->{ content } || '';
 }
@@ -98,6 +136,23 @@ sub prev_chain
 }
 
 
+=head2
+
+=item C<next_chain( $reference_to_message )>
+
+The next one of this message is $reference_to_message.
+
+=item C<prev_chain( $reference_to_message )>
+
+The previous one of this message is $reference_to_message.
+
+=item C<print( $fd )>
+
+print out a chain of messages to the file descriptor $fd.
+If $fd is not specified, STDOUT is used.
+
+=cut
+
 sub print
 {
     my ($self, $fd) = @_;
@@ -152,6 +207,18 @@ sub _print
 }
 
 
+=head2
+
+=item C<size()>
+
+return the message size.
+
+=item C<is_empty()>
+
+return this message has empty content or not.
+
+=cut
+
 sub size
 {
     my ($self) = @_;
@@ -197,8 +264,25 @@ sub AUTOLOAD
     }
 }
 
+=head2
+
+=item C<get_xxx_reference()>
+
+get the reference to xxx, which is a key of the message. 
+For example, 
+C<get_content_reference()>
+returns the reference to the
+content of the message.
+
+=cut
 
 ######################################################################
+
+=head1 TODO
+
+The chain structure of messages is implemented, but 
+MIME/multipart is not yet handled well.
+
 =head1 AUTHOR
 
 Ken'ichi Fukamachi
diff --git a/fml/lib/MailingList/Net/INET4.pm b/fml/lib/MailingList/Net/INET4.pm
index 328bc69b..53ca97ca 100644
--- a/fml/lib/MailingList/Net/INET4.pm
+++ b/fml/lib/MailingList/Net/INET4.pm
@@ -53,30 +53,58 @@ sub _connect4
 
 =head1 NAME
 
-FML::__HERE_IS_YOUR_MODULE_NAME__.pm - what is this
-
+MailingList::Net::INET4 - establish tcp connection over IPv4
 
 =head1 SYNOPSIS
 
+   use MailingList::Net::INET4;
+
+   $mta = '127.0.0.1:25';
+   $self->_connect4( { _mta => $mta });
+
 =head1 DESCRIPTION
 
-=head2 new
+This module tries to create a socket and establish tcp connection over
+IPv4. This is a typical socket program.
+
+=head1 METHODS
+
+=item C<_connect4()>
 
-=item Function()
+try L<connect(2)>. 
+If it succeeds, returned 
+$self->{ _socket } has true value.
+If not, 
+$self->{ _socket } is undef. 
 
+Avaialble arguments follows:
+
+    _connect4( { _mta => $mta });
+
+$mta is a hostname or [raw_ipv4_addr]:port form, for example, 
+127.0.0.1:25.
+
+=head1 SEE ALSO
+
+L<MailingList::SMTP>,
+L<Socket>,
+L<IO::Socket>,
+L<MailingList::Utils>
 
 =head1 AUTHOR
 
+Ken'ichi Fukamachi
+
 =head1 COPYRIGHT
 
-Copyright (C) 2001 __YOUR_NAME__
+Copyright (C) 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. 
 
 =head1 HISTORY
 
-FML::__MODULE_NAME__.pm appeared in fml5.
+MailingList::Net::INET4.pm appeared in fml5.
 
 =cut
 
diff --git a/fml/lib/MailingList/Net/INET6.pm b/fml/lib/MailingList/Net/INET6.pm
index 0559ea1e..df0dc78a 100644
--- a/fml/lib/MailingList/Net/INET6.pm
+++ b/fml/lib/MailingList/Net/INET6.pm
@@ -144,30 +144,64 @@ sub _connect6
 
 =head1 NAME
 
-FML::__HERE_IS_YOUR_MODULE_NAME__.pm - what is this
-
+MailingList::Net::INET6 - establish tcp connection over IPv6 
 
 =head1 SYNOPSIS
 
+    if ($self->is_ipv6_ready($args)) {
+	$self->_connect6($args);
+    }
+
 =head1 DESCRIPTION
 
-=head2 new
+This module tries to create a socket and establish a tcp connection
+over IPv6. It is used within C<MailingList::SMTP> module.
+
+=head1 METHODS
+
+=item C<is_ipv6_ready()>
+
+It checks whether your environment has Socket6.pm or not?
+If Socket6 module exists, we assume your operating system is IPv6 ready!
 
-=item Function()
+=item C<_connect6()>
 
+try L<connect(2)>. 
+If it succeeds, returned 
+$self->{ _socket } has true value.
+If not, 
+$self->{ _socket } is undef. 
+
+Avaialble arguments follows:
+
+    _connect6( { _mta => $mta });
+
+$mta is a hostname or [raw_ipv6_addr]:port form, for example, 
+[::1]:25.
+
+=head1 SEE ALSO
+
+L<MailingList::SMTP>,
+L<Socket6>,
+L<Socket>,
+L<IO::Handle>,
+L<IO::Socket>,
+L<MailingList::Utils>
 
 =head1 AUTHOR
 
+Ken'ichi Fukamachi
+
 =head1 COPYRIGHT
 
-Copyright (C) 2001 __YOUR_NAME__
+Copyright (C) 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. 
 
 =head1 HISTORY
 
-FML::__MODULE_NAME__.pm appeared in fml5.
+MailingList::Net::INET6.pm appeared in fml5.
 
 =cut
 
diff --git a/fml/lib/MailingList/SMTP.pm b/fml/lib/MailingList/SMTP.pm
index a80b0776..4c3ea0aa 100644
--- a/fml/lib/MailingList/SMTP.pm
+++ b/fml/lib/MailingList/SMTP.pm
@@ -23,6 +23,7 @@ require Exporter;
 
 
 BEGIN {}
+END   {}
 
 
 =head1 NAME
@@ -59,6 +60,19 @@ To start delivery, use deliver() method in this way.
 
 =head1 DESCRIPTION
 
+This module provides SMTP/ESMTP mail delivery service.
+It tries IPv6 connection If possible.
+
+The socket creation and tcp connection is controlled by
+sub-classes, 
+C<MailingList::Net::INET4> and
+C<MailingList::Net::INET6>.
+
+It sends all recipients indicated by $recipient_maps.
+The list of recipients for $recipient_maps is resolved by
+L<IO::MapAdapter>.
+
+
 =head1 METHODS
 
 =item C<new()>
@@ -66,11 +80,11 @@ To start delivery, use deliver() method in this way.
 constructor. If you control parameters, specify it in a hash reference
 as an argument of new().
 
-        hash key           value
-        --------------------------------------------
-        log_function       reference to function for logging
-        smtp_log_function  reference to function for logging
-        default_io_timeout set the timeout associated with the socket
+   hash key             value
+   --------------------------------------------
+   log_function         reference to function for logging
+   smtp_log_function    reference to function for logging
+   default_io_timeout   default timeout associated with the socket IO
 
 log_function() is for general purpose.
 smtp_log_function() is used to log SMTP transactions.
@@ -265,14 +279,14 @@ sub close
 
 start delivery process.
 
-        hash key           value
-        --------------------------------------------
-        mta                127.0.0.1:25 [::1]:25
-        smtp_sender        sender's mail address
-        recipient_maps     $recipient_maps
-        recipient_limit    recipients in one SMTP transactions
-        header             FML::Header object
-        body               MailingList::Messages object
+    hash key           value
+    --------------------------------------------
+    mta                127.0.0.1:25 [::1]:25
+    smtp_sender        sender's mail address
+    recipient_maps     $recipient_maps
+    recipient_limit    recipients in one SMTP transactions
+    header             FML::Header object
+    body               MailingList::Messages object
 
 C<mta> is a list of MTA's.
 The syntax of each MTA is address:port style. 
@@ -281,8 +295,8 @@ For example, [::1]:25 (v6 loopback).
 You can specify IPv4 and IPv6 addresses.
 deliver() automatically tries smtp in both protocols.
 
-C<smtp_sender> is the sender's email address. It is used at MAIL FROM:
-parameter.
+C<smtp_sender> is the sender's email address. 
+It is used at MAIL FROM: command.
 
 C<recipient_maps> is a list of C<maps>.
 See L<IO::MapAdapter> for more details. 
@@ -299,9 +313,9 @@ to read addresses from /etc/group
 C<recipient_limit> is the max number of recipients in one SMTP
 transaction. 1000 by default, which corresponds to the limit by Postfix. 
 
-C<header> is FML::Header object.
+C<header> is an FML::Header object.
 
-C<body> is MailingList::Messages object.
+C<body> is a MailingList::Messages object.
 See L<MailingList::Messages> for more details.
 
 =cut
@@ -750,17 +764,17 @@ sub _reset_smtp_transaction
 
 =head1 SEE ALSO
 
-L<IO::Socket>
-L<MailingList::Utils>
-L<MailingList::INET4>
-L<MailingList::INET6>
+L<IO::Socket>,
+L<MailingList::Utils>,
+L<MailingList::INET4>,
+L<MailingList::INET6>,
+L<IO::MapAdapter>
 
 
 =head1 AUTHOR
 
 Ken'ichi Fukamachi
 
-
 =head1 COPYRIGHT
 
 Copyright (C) 2001 Ken'ichi Fukamachi
diff --git a/fml/lib/MailingList/Utils.pm b/fml/lib/MailingList/Utils.pm
index 2730768f..b22c60e7 100644
--- a/fml/lib/MailingList/Utils.pm
+++ b/fml/lib/MailingList/Utils.pm
@@ -10,7 +10,8 @@
 
 package MailingList::Utils;
 use strict;
-use vars qw(@ISA @EXPORT @EXPORT_OK $LogFunctionPointer $SmtpLogFunctionPointer);
+use vars qw(@ISA @EXPORT @EXPORT_OK 
+	    $LogFunctionPointer $SmtpLogFunctionPointer);
 use Carp;
 
 require Exporter;
@@ -41,6 +42,39 @@ require Exporter;
 	     _reset_mapinfo
 	     );
 
+
+=head1 NAME
+
+MailingList::utils - utiliti programs for mail delivery
+
+=head1 SYNOPSIS
+
+For example,
+
+   use MailingList::utils;
+   Log( $message_to_log );
+
+=head1 DESCRIPTION
+
+=cut
+
+#################################################################
+#####
+##### General Logging
+#####
+
+=head2
+
+=item C<Log()>
+
+Logging interface. 
+If CODE REFERENCE is not specified at
+MailingList::Delivery::new(), 
+the logging message is forwarded to STDERR channel.
+
+=cut
+
+
 sub Log
 {
     my ($buf) = @_;
@@ -58,6 +92,21 @@ sub Log
 }
 
 
+#################################################################
+#####
+##### SMTP Logging
+#####
+=head2
+
+=item C<smtplog()>
+
+smtp logging interface.
+If CODE REFERENCE is not specified at
+MailingList::Delivery::new(), 
+the logging message is forwarded to STDERR channel.
+
+=cut
+
 sub smtplog
 {
     my ($self, $buf) = @_;
@@ -81,6 +130,21 @@ sub _smtplog
 }
 
 
+
+#################################################################
+#####
+##### error manipulations
+#####
+=head2
+
+=item C<_error_reason()>
+
+=item C<error()>
+
+=item C<error_reset()>
+
+=cut
+
 sub _error_reason
 {
     my ($self, $mesg) = @_;
@@ -112,11 +176,18 @@ sub error_reset
 }
 
 
-sub _set_status_code
-{
-    my ($self, $value) = @_;
-    $self->{'_status_code'} = $value;
-}
+#################################################################
+#####
+##### status codes manipulations
+#####
+
+=head2
+
+=item C<_get_status_code()>
+
+=item C<_set_status_code(value)>
+
+=cut
 
 
 sub _get_status_code
@@ -126,12 +197,39 @@ sub _get_status_code
 }
 
 
+sub _set_status_code
+{
+    my ($self, $value) = @_;
+    $self->{'_status_code'} = $value;
+}
 
-############################################################
+
+
+
+#################################################################
 #####
-##### utility functions to operate $recipient_maps
+##### utility to control $recipient_map
 #####
 
+=head2
+
+=item	     C<_set_target_map()>
+
+=item	     C<_get_target_map()>
+
+=item	     C<_set_map_status()>
+
+=item	     C<_set_map_position()>
+
+=item	     C<_get_map_status()>
+
+=item	     C<_get_map_position()>
+
+=item	     C<_rollback_map_position()>
+
+=item	     C<_reset_mapinfo()>
+
+=cut
 
 sub _set_target_map
 {
@@ -211,7 +309,22 @@ sub _reset_mapinfo
 }
 
 
-1;
 
+=head1 AUTHOR
+
+Ken'ichi Fukamachi
+
+=head1 COPYRIGHT
+
+Copyright (C) 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. 
+
+=head1 HISTORY
+
+MailingList::utils.pm appeared in fml5.
+
+=cut
 
 1;