clean up documents

5 files changed, 118 insertions, 64 deletions

diff --git a/fml/doc/purpose.ja.html b/fml/doc/purpose.ja.html
index bc2f6d77..cabc704f 100644
--- a/fml/doc/purpose.ja.html
+++ b/fml/doc/purpose.ja.html
@@ -20,7 +20,7 @@ fml5 プロジェクトの目的
    <A HREF="http://www.fml.org/devel/">http://www.fml.org/devel/</A>
 )
 は将来の fml-current についてのデザインや実装例を紹介しています。
-おおまかにいえば fml 4.0 の再構想 (refactoring)です。
+おおまかにいえば fml 4.0 の再構想(refactoring)です。
 
 <P>
 これは fml 5.0 のアイデアを募るための、
@@ -38,7 +38,18 @@ fml5 プロジェクトの目的
 
 <P>
 ものによっては fml 5.0 用に作られたモジュールを fml 4.0 へ
-戻すことも検討しています。
+輸入することも検討しています。
+たとえば 4.0 でも独立性の高い mead (エラーメール解析プログラム)などは
+その良い例だろうし、新機能を提供するモジュールなども再輸入(輸出)可能な
+ものは順次マージしていきます。
+
+<P>
+これらのマージおよび 4.0 自体のコードの保守をしつつ 4.0 および 5.0 は
+並行開発されていく予定です。
+そのため 4.0 系は stable に近い current という位置付けになります。
+そして 4.0 の bug fix は 4.0.x (4.0.1 4.0.2 …)としてまとめられリリー
+スれていく予定です。
+逆に 5.0 は本当の開発用のコード( fml-current )ということになります。
 
 <P>
 ご意見・御感想をお待ちしております。
diff --git a/fml/lib/MailingList/Delivery.pm b/fml/lib/MailingList/Delivery.pm
index 282f0185..c012cb9a 100644
--- a/fml/lib/MailingList/Delivery.pm
+++ b/fml/lib/MailingList/Delivery.pm
@@ -49,7 +49,7 @@ Please see it for more details.
 =head1 DESCRIPTION
 
 In C<MailingList> class, 
-C<Delivery> is an adapter which composes
+C<Delivery> is an adapter to
 C<SMTP>
 C<ESMTP>
 C<LMTP> classes. 
@@ -83,6 +83,9 @@ sub new
     my ($self, $args) = @_;
     my $protocol =  $args->{ protocol } || 'SMTP';
     my $pkg      = 'MailingList::SMTP';
+
+    # char's of the protocol name is aligned to upper case.
+    $protocol =~ tr/A-Z/a-z/;
  
     if ($protocol eq 'SMTP') {
 	$pkg = 'MailingList::SMTP';
diff --git a/fml/lib/MailingList/SMTP.pm b/fml/lib/MailingList/SMTP.pm
index be1f9da2..56abcbdf 100644
--- a/fml/lib/MailingList/SMTP.pm
+++ b/fml/lib/MailingList/SMTP.pm
@@ -58,10 +58,10 @@ To start delivery, use deliver() method in this way.
                           body            => $body_object,
                       });
 
-You can use ARRAY REFERENCE.
+You can specify the recipient list as an ARRAY REFERENCE.
 
     # reference to an array of recipients
-    $raaray = [ 'kenken@nuinui.net' ];
+    $rarray = [ 'kenken@nuinui.net' ];
 
     $service->deliver(
                       {
@@ -85,17 +85,18 @@ 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>.
-
+It sends a list of all recipients indicated by $recipient_maps.
+C<IO::MapAdapter> resolves $recipient_maps and provides the abstract
+IO layer. It provides the usual file IO methods for each C<map>.
+See L<IO::MapAdapter> for more details.
 
 =head1 METHODS
 
-=item C<new()>
+=item C<new($args)>
 
-constructor. If you control parameters, specify it in a hash reference
-as an argument of new().
+the constructor. 
+Please specify it in a hash reference as an argument of new().
+Several parameters on logging and timeout et. al. are avialable.
 
    hash key             value
    --------------------------------------------
@@ -103,8 +104,10 @@ as an argument of new().
    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.
+C<log_function()> is the function pointer to write a message in the
+log file.  
+C<smtp_log_function()> is special function pointer to log SMTP
+transactions.
 
 =cut
 
@@ -292,9 +295,10 @@ sub close
 ##### SMTP delivery main loop
 #####
 
-=item C<deliver()>
+=item C<deliver($args)>
 
 start delivery process.
+You can specify the following parameter at C<$args> HASH REFERENCE.
 
     hash key           value
     --------------------------------------------
@@ -305,12 +309,13 @@ start delivery process.
     header             FML::Header object
     body               MailingList::Messages object
 
-C<smtp_servers> is a list of MTA's.
-The syntax of each MTA is address:port style. 
-If you use a raw IPv6 address, use [address]:port syntax. 
-For example, [::1]:25 (v6 loopback).
-You can specify IPv4 and IPv6 addresses.
-deliver() automatically tries smtp in both protocols.
+C<smtp_servers> is a list of MTA's (Mail Transport Agents).
+The syntax of each MTA is C<host:port> or C<address:port> style. 
+If you use a raw IPv6 address, use C<[address]:port> syntax. 
+For example, [::1]:25 (IPv6 loopback address).
+You can specify a combination of IPv4 and IPv6 addresses at
+C<smtp_servers>.
+C<deliver()> automatically tries smtp connection on both protocols.
 
 C<smtp_sender> is the sender's email address. 
 It is used at MAIL FROM: command.
@@ -319,20 +324,21 @@ C<recipient_maps> is a list of C<maps>.
 See L<IO::MapAdapter> for more details. 
 For example,
 
-to read address from a file
+To read addresses from a file, specify the map as
 
          file:/var/spool/ml/elena/recipients
 
-to read addresses from /etc/group
+and to read addresses from /etc/group
 
          unix.group:fml
 
 C<recipient_limit> is the max number of recipients in one SMTP
-transaction. 1000 by default, which corresponds to the limit by Postfix. 
+transaction. 1000 by default, 
+which corresponds to the limit by C<Postfix>. 
 
-C<header> is an FML::Header object.
+C<header> is an C<FML::Header> object.
 
-C<body> is a MailingList::Messages object.
+C<body> is a C<MailingList::Messages> object.
 See L<MailingList::Messages> for more details.
 
 =cut
@@ -773,6 +779,9 @@ L<MailingList::INET4>,
 L<MailingList::INET6>,
 L<IO::MapAdapter>
 
+See I<http://www.postfix.org/> on C<Postfix> 
+which replaces sendmail with little effort 
+but provides a lot of compatibility except for sendmail.cf.
 
 =head1 AUTHOR
 
diff --git a/fml/lib/MailingList/Utils.pm b/fml/lib/MailingList/Utils.pm
index 7d56113d..3db39fc9 100644
--- a/fml/lib/MailingList/Utils.pm
+++ b/fml/lib/MailingList/Utils.pm
@@ -56,6 +56,8 @@ For example,
 
 =head1 DESCRIPTION
 
+several utility functions for C<MailingList> sub classes.
+
 =cut
 
 #################################################################
@@ -63,13 +65,16 @@ For example,
 ##### General Logging
 #####
 
-=head2
+=head1 LOGGING FUNCTIONS
 
-=item C<Log()>
+=head2 C<Log($buf)>
 
 Logging interface. 
-If CODE REFERENCE is not specified at
-MailingList::Delivery::new(), 
+send C<$buf> (the log message) to the function specified as
+C<$LogFunctionPointer> (CODE REFERENCE).
+C<$LogFunctionPointer> is expected to set up at
+C<MailingList::Delivery::new()>
+If it is not specified,
 the logging message is forwarded to STDERR channel.
 
 =cut
@@ -96,14 +101,14 @@ sub Log
 #####
 ##### SMTP Logging
 #####
-=head2
 
-=item C<smtplog()>
+=head2 C<smtplog($buf)>
 
-smtp logging interface.
-If CODE REFERENCE is not specified at
-MailingList::Delivery::new(), 
-the logging message is forwarded to STDERR channel.
+smtp logging interface as the same as C<Log()> but for smtp
+transcation log.
+If the real log function pointer is not specified at
+C<MailingList::Delivery::new()>, 
+C<$buf> is sent to C<STDERR>.
 
 =cut
 
@@ -132,16 +137,20 @@ sub _smtplog
 
 
 #################################################################
-#####
-##### error manipulations
-#####
-=head2
 
-=item C<_error_reason()>
+=head1 METHODS FOR ERROR MESSAGES AND STATUS CODES
+
+=head2 C<error_reason($mesg)>
+
+save C<$mesg>.
+
+=head2 C<error()>
+
+return the latest error message which saved by C<error_reason()>.
 
-=item C<error()>
+=head2 C<error_reset()>
 
-=item C<error_reset()>
+reset the error buffer which C<error_reason()> and C<error()> use.
 
 =cut
 
@@ -181,11 +190,13 @@ sub error_reset
 ##### status codes manipulations
 #####
 
-=head2
+=head2 C<_set_status_code($value)>
 
-=item C<_get_status_code()>
+save C<($value)> as status code.
 
-=item C<_set_status_code(value)>
+=head2 C<_get_status_code()>
+
+get the latest status code.
 
 =cut
 
@@ -211,23 +222,17 @@ sub _set_status_code
 ##### utility to control $recipient_map
 #####
 
-=head2
-
-=item	     C<_set_target_map()>
-
-=item	     C<_get_target_map()>
-
-=item	     C<_set_map_status()>
+=head1 METHODS TO HANDLE POSITION at IO MAP
 
-=item	     C<_set_map_position()>
+=head2	     C<_set_target_map($map)>
 
-=item	     C<_get_map_status()>
+save the current C<map> name
+where C<map> is a name usable at C<recipient_maps>
 
-=item	     C<_get_map_position()>
+=head2	     C<_get_target_map()>
 
-=item	     C<_rollback_map_position()>
-
-=item	     C<_reset_mapinfo()>
+return the current C<map>
+where C<map> is a name usable at C<recipient_maps>
 
 =cut
 
@@ -245,6 +250,25 @@ sub _get_target_map
 }
 
 
+=head2	     C<_set_map_status($map, $status)>
+
+save C<$status> for C<$map> IO.
+For example, C<$status> is 'not done'.
+
+=head2	     C<_set_map_position($map, $position)>
+
+save the C<$position> for C<$map> IO.
+
+=head2	     C<_get_map_status($map)>
+
+get the current C<$status> for C<$map> IO.
+
+=head2	     C<_get_map_position($map)>
+
+get the current C<$position> for C<$map> IO.
+
+=cut
+
 sub _set_map_status
 {
     my ($self, $map, $status) = @_;
@@ -274,6 +298,18 @@ sub _get_map_position
 }
 
 
+=head2	     C<_rollback_map_position()>
+
+stop the IO for the current C<$map>.
+This method rolls back the operation state to the time when the
+current IO for C<$map> begins.
+
+=head2	     C<_reset_mapinfo()>
+
+clear information around the latest map operation.
+
+=cut
+
 sub _rollback_map_position
 {
     my ($self) = @_;
diff --git a/regress/simulation/todo/doc b/regress/simulation/todo/doc
index eda71297..14ca7f54 100644
--- a/regress/simulation/todo/doc
+++ b/regress/simulation/todo/doc
@@ -1,12 +1,7 @@
 FML/Config.pm
 FML/Credential.pm
 
-MailingList/Delivery.pm
 MailingList/Messages.pm
-MailingList/SMTP.pm
-MailingList/Utils.pm
-
-
 
 --- not yet implemented ---