clean up and add missing descriptions

4 files changed, 120 insertions, 19 deletions

diff --git a/fml/lib/FML/Article.pm b/fml/lib/FML/Article.pm
index 2a727451..e6c064da 100644
--- a/fml/lib/FML/Article.pm
+++ b/fml/lib/FML/Article.pm
@@ -83,6 +83,8 @@ sub _setup_article_template
 increment article sequence number and 
 save it to C<$sequence_file>.
 
+This routine uses C<File::Sequence> module. 
+
 =head2 C<id()>
 
 return the current article sequence number.
@@ -174,7 +176,8 @@ sub spool_in
 =head1 SEE ALSO
 
 L<FML::Header>,
-L<MailingList::Messsages>.
+L<MailingList::Messsages>,
+L<File::Sequence>
 
 =head1 AUTHOR
 
diff --git a/fml/lib/FML/Checksum.pm b/fml/lib/FML/Checksum.pm
index e338eeef..055c8bc0 100644
--- a/fml/lib/FML/Checksum.pm
+++ b/fml/lib/FML/Checksum.pm
@@ -12,6 +12,7 @@ package FML::Checksum;
 use strict;
 use vars qw(@ISA @EXPORT @EXPORT_OK $AUTOLOAD);
 use Carp;
+use FML::Log qw(Log);
 
 =head1 NAME
 
@@ -28,8 +29,8 @@ FML::Checksum - utilities for check sum
 =head2 C<new()>
 
 the constructor. 
-It checks we can use MD5 perl module or should use some programs e.g. 
-C<md5>, C<cksum>, et.al.
+It checks we can use MD5 perl module or we need to use some programs
+e.g. C<md5>, C<cksum>, et.al.
 
 =cut
 
@@ -147,7 +148,7 @@ sub _md5_by_program
 
 =head2 C<cksum1($file)>
 
-not implemented.
+C<not implemented>.
 
 This is a 16-bit checksum. The algorithm used by historic BSD systems
 as the sum(1) algorithm and by historic AT&T System V UNIX systems as
@@ -186,7 +187,7 @@ sub cksum2
         $crc = ($crc & 0xffff) + ($crc >> 16);
     }
     else {
-        print STDERR "ERROR: no such file $f\n";
+        Log("ERROR: no such file $f");
     }
 
     ($crc, $total);
@@ -195,7 +196,7 @@ sub cksum2
 
 =head2 C<crc($file)>
 
-not implemented.
+C<not implemented>.
 
 The default CRC used is based on the polynomial used for CRC error
 checking in the networking standard ISO 8802-3:1989 The CRC checksum
diff --git a/fml/lib/FML/Header.pm b/fml/lib/FML/Header.pm
index e3f3c744..3c0f6405 100644
--- a/fml/lib/FML/Header.pm
+++ b/fml/lib/FML/Header.pm
@@ -25,20 +25,34 @@ FML::Header - header manipulators
 
     $header = use FML::Header \@header;
     $header->add('X-ML-Info', "mailing list name");
-    
+    $header->delete('Return-Receipt-To');
+    $header->replace(field, value);
+
 =head1 DESCRIPTION
 
-FML::Header is an adapter for Mail::Address class.
-That is, Mail::Address is the base class. 
+C<FML::Header> is an adapter for C<Mail::Header> class.
+C<Mail::Header> is the base class. 
 
 =head1 METHODS
 
+Methods defined in C<Mail::Header> are available.
+For example,
+C<modify()>, C<mail_from()>, C<fold()>, C<extract()>, C<read()>,
+C<empty()>, C<header()>, C<header_hashref()>, C<add()>, C<replace()>,
+C<combine()>, C<get()>, C<delete()>, C<count()>, C<print()>,
+C<as_string()>, C<fold_length()>, C<tags()>, C<dup()>, C<cleanup()>,
+C<unfold()>.
+
 =cut
 
 require Exporter;
 @ISA = qw(Mail::Header Exporter);
 
 
+# Descriptions: forward new() request to the base class
+#    Arguments: $self $args
+# Side Effects: none
+# Return Value: none
 sub new
 {
     my ($self, $args) = @_;
@@ -58,6 +72,20 @@ sub AUTOLOAD
 }
 
 
+=head2 C<content_type()>
+
+return the C<type> defind in the header's Content-Type field.
+
+=head2 C<mime_boundary()>
+
+return the C<boundary> defind in the header's Content-Type field.
+
+=cut
+
+# Descriptions: return the type defind in the header's Content-Type field.
+#    Arguments: $self
+# Side Effects: extra spaces in the type to return is removed.
+# Return Value: none
 sub content_type
 {
     my ($header) = @_;
@@ -66,9 +94,14 @@ sub content_type
 	$type =~ s/\s*//g;
 	return $type;
     }
+    undef;
 }
 
 
+# Descriptions: return boundary defined in Content-Type
+#    Arguments: $self $args
+# Side Effects: none.
+# Return Value: none
 sub mime_boundary
 {
     my ($header) = @_;
@@ -83,10 +116,30 @@ sub mime_boundary
 }
 
 
+###
+### FML specific functions
+###
+
+=head1 FML SPECIFIC METHODS
+
+=head2 C<add_fml_ml_name($config, $args)>
+
+add X-ML-Name:
+
+=head2 C<add_fml_traditional_article_id($config, $args)>
+
+add X-Mail-Count:
+
+=head2 C<add_fml_article_id($config, $args)>
+
+add X-ML-Count:
+
+=cut
+
+
 sub add_fml_ml_name
 {
     my ($header, $config, $args) = @_;
-
     $header->add('X-ML-Name', $config->{ x_ml_name });
 }
 
@@ -105,6 +158,21 @@ sub add_fml_article_id
 }
 
 
+=head2 C<add_software_info($config, $args)>
+
+add X-MLServer: and List-Software:
+
+=head2 C<add_rfc2369($config, $args)>
+
+add List-* sereies defined in RFC2369.
+
+=head2 C<add_x_sequence($config, $args)>
+
+add X-Sequence.
+
+=cut
+
+
 sub add_software_info
 {
     my ($header, $config, $args) = @_;
@@ -147,6 +215,18 @@ sub add_x_sequence
 }
 
 
+=head2 C<rewrite_subject_tag($config, $args)>
+
+add subject tag e.g. [elena:00010]. 
+The real function exists in C<FML::Header::Subject>.
+
+=head2 C<rewrite_reply_to>
+
+add or replace C<Reply-To:>.
+
+=cut
+
+
 sub rewrite_subject_tag
 {
     my ($header, $config, $args) = @_;
@@ -172,15 +252,11 @@ sub rewrite_reply_to
 }
 
 
-sub remove_subject_tag_like_string
-{
-    my ($str) = @_;
-    $str =~ s/\W[-\w]+.\s*\d+\W//g;
-    $str =~ s/\s+/ /g;
-    $str =~ s/^\s*//g;
-    $str;
-}
+=head2 C<delete_unsafe_header_fields($config, $args)>
+
+remove header fields defiend in C<$unsafe_header_fields>.
 
+=cut
 
 sub delete_unsafe_header_fields
 {
@@ -190,9 +266,28 @@ sub delete_unsafe_header_fields
 }
 
 
+=head1 MISCELLANEOUS UTILITIES
+
+=head2 C<remove_subject_tag_like_string($string)>
+
+remove subject tag like string in C<$string>.
+
+=cut
+
+
+sub remove_subject_tag_like_string
+{
+    my ($str) = @_;
+    $str =~ s/\W[-\w]+.\s*\d+\W//g;
+    $str =~ s/\s+/ /g;
+    $str =~ s/^\s*//g;
+    $str;
+}
+
+
 =head1 SEE ALSO
 
-L<Mail::Address>
+L<Mail::Header>
 
 =head1 AUTHOR
 
diff --git a/fml/lib/FML/Messages.pm b/fml/lib/FML/Messages.pm
index 29bde296..a7540006 100644
--- a/fml/lib/FML/Messages.pm
+++ b/fml/lib/FML/Messages.pm
@@ -25,6 +25,8 @@ NOT YET IMPLEMENTED
 
 =head1 DESCRIPTION
 
+NOT YET IMPLEMENTED
+
 =cut