clean up doc

7 files changed, 254 insertions, 133 deletions

diff --git a/fml/lib/Dialect/Japanese/Subject.pm b/fml/lib/Dialect/Japanese/Subject.pm
index 1f95431e..dc67608c 100644
--- a/fml/lib/Dialect/Japanese/Subject.pm
+++ b/fml/lib/Dialect/Japanese/Subject.pm
@@ -8,12 +8,29 @@
 # $FML$
 #
 
+
+###                                                   ###
+### CAUTION: THE CHARSET OF THIS FILE IS "EUC-JAPAN". ###
+###                                                   ###
+
+
 package Dialect::Japanese::Subject;
 use strict;
 use vars qw(@ISA @EXPORT @EXPORT_OK);
 use Carp;
 use Jcode;
 
+=head1 NAME
+
+Dialect::Japanese::Subject - what is this
+
+=head1 SYNOPSIS
+
+=head1 DESCRIPTION
+
+=cut
+
+
 require Exporter;
 @ISA = qw(Exporter);
 
@@ -31,6 +48,23 @@ my $pattern  = 'Re:|Re\d+:|Re\[\d+\]:|Re\(\d+\):|Re\^\d+:|Re\*\d+:';
    $pattern .= '|(返信|返|ＲＥ|Ｒｅ)(\s*:|：)';
 
 
+=head1 METHODS
+
+=head2 C<new()>
+
+usual constructor.
+
+=head2 C<is_reply($string)>
+
+check whether C<$string> looks like a reply message.
+C<$string> is a C<Subject:> of the mail header.
+For example, it is like this:
+
+  Re: reply to your messages
+
+=cut
+
+
 sub new
 {
     my ($self) = @_;
@@ -40,6 +74,23 @@ sub new
 }
 
 
+sub is_reply
+{
+    my ($self, $x) = @_;
+    return 0 unless $x;
+    &Jcode::convert(\$x, 'euc');
+    return ($x =~ /^((\s|(　))*($pattern)\s*)+/ ? 1 : 0);
+}
+
+
+=head2 C<cut_off_reply_tag($subject)>
+
+cut off C<Re:> in the string C<$subject> like C<Re: ... >, 
+which is a C<Subject:> in typical case.
+
+=cut
+
+
 # fml-support: 07507
 # sub CutOffRe
 # {
@@ -82,29 +133,6 @@ sub cut_off_reply_tag
 }
 
 
-sub is_reply
-{
-    my ($self, $x) = @_;
-    return 0 unless $x;
-    &Jcode::convert(\$x, 'euc');
-    return ($x =~ /^((\s|(　))*($pattern)\s*)+/ ? 1 : 0);
-}
-
-
-=head1 NAME
-
-Dialect::Japanese::Subject.pm - what is this
-
-
-=head1 SYNOPSIS
-
-=head1 DESCRIPTION
-
-=head2 new
-
-=item Function()
-
-
 =head1 AUTHOR
 
  Ken'ichi Fukamachi
diff --git a/fml/lib/FML/Article.pm b/fml/lib/FML/Article.pm
index 19571e61..2a727451 100644
--- a/fml/lib/FML/Article.pm
+++ b/fml/lib/FML/Article.pm
@@ -15,7 +15,33 @@ use vars qw(@ISA @EXPORT @EXPORT_OK);
 use Carp;
 use FML::Log qw(Log);
 
-require Exporter;
+
+=head1 NAME
+
+FML::Article - article manipulation components
+
+=head1 SYNOPSIS
+
+   use FML::Article;
+   $article = new FML::Article $curproc;
+   $header  = $article->{ header };
+   $body    = $article->{ body };
+
+=head1 DESCRIPTION
+
+$article object is just a container which holds 
+C<header> and C<body> object as hash keys.
+The C<header> is an FML::Header object and
+the C<body> is a MailingList::Messages object.
+
+=head1 METHODS
+
+=head2 C<new(curproc)>
+
+prepare a message duplicated from the incoming message holded in
+C<$curproc->{ incoming_message }>.
+
+=cut
 
 
 # Descriptions: constructor
@@ -52,6 +78,18 @@ sub _setup_article_template
 }
 
 
+=head2 C<increment_id()>
+
+increment article sequence number and 
+save it to C<$sequence_file>.
+
+=head2 C<id()>
+
+return the current article sequence number.
+
+=cut
+
+
 # Descriptions: determine article id (sequence number)
 #    Arguments: $self
 # Side Effects: record the current article sequence number
@@ -75,6 +113,10 @@ sub increment_id
 }
 
 
+# Descriptions: return the article id (sequence number)
+#    Arguments: $self
+# Side Effects: none
+# Return Value: number (sequence number)
 sub id
 {
     my ($self) = @_;
@@ -84,6 +126,14 @@ sub id
 }
 
 
+=head2 C<spool_in(id)>
+
+save the article to the file name C<id> in the article spool.
+If the variable C<$use_spool> is 'yes', this routine works.
+
+=cut
+
+
 # Descriptions: spool in the article
 #    Arguments: $self $curproc
 # Side Effects: 
@@ -121,18 +171,10 @@ sub spool_in
 }
 
 
+=head1 SEE ALSO
 
-=head1 NAME
-
-FML::Article - article manipulation components
-
-=head1 SYNOPSIS
-
-... not yet documented ...
-
-=head1 DESCRIPTION
-
-... not yet documented ...
+L<FML::Header>,
+L<MailingList::Messsages>.
 
 =head1 AUTHOR
 
@@ -153,5 +195,4 @@ See C<http://www.fml.org/> for more details.
 =cut
 
 
-
 1;
diff --git a/fml/lib/FML/Credential.pm b/fml/lib/FML/Credential.pm
index 5fa50934..81a31462 100644
--- a/fml/lib/FML/Credential.pm
+++ b/fml/lib/FML/Credential.pm
@@ -14,8 +14,30 @@ use strict;
 use vars qw(%Credential @ISA @EXPORT @EXPORT_OK);
 use Carp;
 
-require Exporter;
-@ISA = qw(Exporter);
+
+=head1 NAME
+
+FML::Credential - authenticate the mail sender is a ML member or not
+
+=head1 SYNOPSIS
+
+   use FML::Credential;
+
+   # get the mail sender
+   my $sender = FML::Credential->sender;
+
+=head1 DESCRIPTION
+
+a collection of utilitity functions to authenticate the sender who
+kicks off this mail.
+
+=head1 METHODS
+
+=head2 C<new()>
+
+bind \%Credential to $self and return it as an object.
+
+=cut
 
 
 sub new
@@ -30,18 +52,47 @@ sub new
 sub DESTROY {}
 
 
-sub is_member
-{
-    1;
-}
+=head2 C<is_member()>
+
+not yet implemented
+
+=head2 C<sender()>
 
+return the mail address of the mail sender who kicks off this fml
+process.
+
+=cut
 
+
+# Descriptions: 
+#    Arguments: $self $args
+# Side Effects: 
+# Return Value: none
+sub is_member { 1;}
+
+
+# Descriptions: 
+#    Arguments: $self $args
+# Side Effects: 
+# Return Value: none
 sub sender
 {
     my ($self) = @_;
     $Credential{ sender };
 }
 
+
+=head2 C<get(key)>
+
+=head2 C<set(key, value)>
+
+=cut
+
+
+# Descriptions: 
+#    Arguments: $self $args
+# Side Effects: 
+# Return Value: none
 sub get
 {
     my ($self, $key) = @_;
@@ -49,6 +100,10 @@ sub get
 }
 
 
+# Descriptions: 
+#    Arguments: $self $args
+# Side Effects: 
+# Return Value: none
 sub set
 {
     my ($self, $key, $value) = @_;
@@ -56,20 +111,6 @@ sub set
 }
 
 
-=head1 NAME
-
-FML::Credential.pm - what is this
-
-
-=head1 SYNOPSIS
-
-=head1 DESCRIPTION
-
-=head2 new
-
-=item Function()
-
-
 =head1 AUTHOR
 
 Ken'ichi Fukamachi
diff --git a/fml/lib/FML/Parse.pm b/fml/lib/FML/Parse.pm
index 11f05d9f..f25826bc 100644
--- a/fml/lib/FML/Parse.pm
+++ b/fml/lib/FML/Parse.pm
@@ -10,6 +10,14 @@
 
 package FML::Parse;
 
+use vars qw($InComingMessage);
+use strict;
+use Carp;
+use FML::Header;
+use MailingList::Messages;
+use FML::Config;
+use FML::Log qw(Log);
+
 
 =head1 NAME
 
@@ -28,45 +36,15 @@ $r_header is the reference to the header object, which is returned by
 Mail::Header class. $r_body is reference to the scalar mail body
 variable, which is alloced in FML::Parse name space.
 
-=head1 METHOD
+=head1 METHODS
 
 =item new( fd )
 
 C<fd> is the file handle. 
 Normally C<fd> is the handle for STDIN channel.
 
-=head1 SEE ALSO
-
-L<Mail::Header>,
-
-=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
-
-FML::Parse appeared in fml5 mailing list driver package.
-See C<http://www.fml.org/> for more details.
-
 =cut
 
-
-use vars qw($InComingMessage);
-use strict;
-use Carp;
-use FML::Header;
-use MailingList::Messages;
-use FML::Config;
-use FML::Log qw(Log);
-
-
 sub new
 {
     my ($self, $curproc, $fd) = @_;
@@ -136,6 +114,7 @@ sub _parse
 
 =head1 SEE ALSO
 
+L<Mail::Header>,
 L<FML::Header>,
 L<MailingList::Messages>,
 L<FML::Config>,
diff --git a/fml/lib/FML/Process/Flow.pm b/fml/lib/FML/Process/Flow.pm
index d88d11d0..fc72abcc 100644
--- a/fml/lib/FML/Process/Flow.pm
+++ b/fml/lib/FML/Process/Flow.pm
@@ -15,39 +15,40 @@ use Carp;
 
 =head1 NAME
 
-FML::Process::Flow - what is this
+FML::Process::Flow - describe process flow 
 
 =head1 SYNOPSIS
 
-=head1 DESCRIPTION
-
-=head1 CLASSES
-
-=head1 METHODS
+   use FML::Process::Flow;
+   FML::Process::Flow::ProcessStart($pkg, $args);
 
-=item C<new()>
+where C<$pkg> is the package name.
+C<$args> is HASH REFERENCE.
 
-... what is this ...
-
-=head1 AUTHOR
+=head1 DESCRIPTION
 
-Ken'ichi Fukamachi
+This is the current fml program flow. 
+Each function is implemented in each module in FML::Process class.
 
-=head1 COPYRIGHT
+    # create a new process object
+    my $process = $pkg->new($args);
 
-Copyright (C) 2001 Ken'ichi Fukamachi
+    # e.g. parse the incoming message (e.g. STDIN)
+    $process->prepare($args);
 
-All rights reserved. This program is free software; you can
-redistribute it and/or modify it under the same terms as Perl itself. 
+    # validate the request, for example,
+    #    permit post from the sender,
+    #    check the mail loop or not ...
+    $process->verify_request($args);
 
-=head1 HISTORY
+    # start main transaction
+    $process->run($args);
 
-FML::Process::Flow appeared in fml5 mailing list driver package.
-See C<http://www.fml.org/> for more details.
+    # closing the process
+    $process->finish($args);
 
 =cut
 
-
 # Descriptions: drives basic flow 
 #               1. initialize processes and load configurations from *.cf
 #                  switch to each process according with $0 and @ARGV.
@@ -82,4 +83,23 @@ sub ProcessStart
 }
 
 
+=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
+
+FML::Process::Flow appeared in fml5 mailing list driver package.
+See C<http://www.fml.org/> for more details.
+
+=cut
+
+
 1;
diff --git a/fml/lib/IO/Adapter/NIS.pm b/fml/lib/IO/Adapter/NIS.pm
index b2daa7f3..1b7ded31 100644
--- a/fml/lib/IO/Adapter/NIS.pm
+++ b/fml/lib/IO/Adapter/NIS.pm
@@ -17,6 +17,7 @@ use IO::Adapter::Array;
 
 @ISA = qw(IO::Adapter::Array);
 
+
 sub configure
 {
     my ($self, $me) = @_;
@@ -30,22 +31,40 @@ sub configure
 }
 
 
-
 =head1 NAME
 
-IO::Adapter::NIS.pm - what is this
+IO::Adapter::NIS.pm - NIS map definition under IO::MapAdapter
 
 =head1 SYNOPSIS
 
+    $map = 'nis.group:fml';
+
+    use IO::MapAdapter;
+    $obj = new IO::MapAdapter $map;
+    $obj->open || croak("cannot open $map");
+    while ($x = $obj->getline) { ... }
+    $obj->close;
+
+/etc/group has C<fml> entry like this:
+
+  fml:*:1000:fukachan
+
+
 =head1 DESCRIPTION
 
-=head1 CLASSES
+fake IO for 
+NIS (Network Information System, its old name is Yellow Page).
+See L<IO::Adapter::Array> for more details.
+
+C<CAUTION: this map is read only>.
 
 =head1 METHODS
 
-=item C<new()>
+See L<IO::Adapter::Array>
 
-... what is this ...
+=head1 SEE ALSO
+
+L<IO::Adapter::Array>
 
 =head1 AUTHOR
 
@@ -65,4 +84,5 @@ See C<http://www.fml.org/> for more details.
 
 =cut
 
+
 1;
diff --git a/fml/lib/IO/Adapter/RDBMS.pm b/fml/lib/IO/Adapter/RDBMS.pm
index 5ad510ae..a21b487e 100644
--- a/fml/lib/IO/Adapter/RDBMS.pm
+++ b/fml/lib/IO/Adapter/RDBMS.pm
@@ -13,39 +13,30 @@ use strict;
 use vars qw(@ISA @EXPORT @EXPORT_OK $AUTOLOAD);
 use Carp;
 
-require Exporter;
-@ISA = qw(Exporter);
-
-
-sub new
-{
-    my ($self) = @_;
-    my ($type) = ref($self) || $self;
-    my $me     = {};
-    return bless $me, $type;
-}
-
-
-#####
-##### This is just a dummy yet now.
-#####
-
 
 =head1 NAME
 
-IO::Adapter::RDBMS.pm - what is this
+IO::Adapter::RDBMS.pm - IO with SQL databases
 
 =head1 SYNOPSIS
 
+... not yet ...
+
 =head1 DESCRIPTION
 
-=head1 CLASSES
+... not yet ...
 
-=head1 METHODS
+=cut
 
-=item C<new()>
 
-... what is this ...
+sub new
+{
+    my ($self) = @_;
+    my ($type) = ref($self) || $self;
+    my $me     = {};
+    return bless $me, $type;
+}
+
 
 =head1 AUTHOR
 
@@ -65,4 +56,5 @@ See C<http://www.fml.org/> for more details.
 
 =cut
 
+
 1;