fix comments. add return() if not specified.

2 files changed, 30 insertions, 20 deletions

diff --git a/fml/lib/FML/Header/MessageID.pm b/fml/lib/FML/Header/MessageID.pm
index 04a4ffac..c41615e1 100644
--- a/fml/lib/FML/Header/MessageID.pm
+++ b/fml/lib/FML/Header/MessageID.pm
@@ -4,7 +4,7 @@
 #   All rights reserved. This program is free software; you can
 #   redistribute it and/or modify it under the same terms as Perl itself.
 #
-# $FML: MessageID.pm,v 1.9 2002/09/28 09:27:43 fukachan Exp $
+# $FML: MessageID.pm,v 1.10 2002/12/18 04:26:53 fukachan Exp $
 #
 
 package FML::Header::MessageID;
@@ -69,7 +69,7 @@ open db and return HASH_REF for the db access.
 # Descriptions: open message-id database
 #    Arguments: OBJ($self) HASH_REF($args)
 # Side Effects: none
-# Return Value: OBJ
+# Return Value: HASH_ERF
 sub db_open
 {
     my ($self, $args) = @_;
@@ -79,6 +79,7 @@ sub db_open
 
     if ($dir) {
 	unless (-d $dir) {
+	    # XXX-TODO: dir_mode is hard-coded ?
 	    my $dir_mode = $self->{ _dir_mode } || 0700;
 
 	    use File::Path;
@@ -126,6 +127,7 @@ sub get
     my ($self, $key) = @_;
     my $db = $self->{ _db };
 
+    # XXX-TODO: what should we do if undefined ?
     if (defined $db) {
 	return $db->{ $key };
     }
@@ -168,8 +170,9 @@ sub gen_id
     my ($self, $curproc, $args) = @_;
     my $config = $curproc->{ config };
 
+    # XXX-TODO: if $config->{ address_for_post } undefined ?
     $Counter++;
-    time.".$$.$Counter\@" . $config->{ address_for_post };
+    return time.".$$.$Counter\@" . $config->{ address_for_post };
 }
 
 
diff --git a/fml/lib/FML/Header/Subject.pm b/fml/lib/FML/Header/Subject.pm
index 08d56a95..9ec7ef63 100644
--- a/fml/lib/FML/Header/Subject.pm
+++ b/fml/lib/FML/Header/Subject.pm
@@ -4,7 +4,7 @@
 #   All rights reserved. This program is free software; you can
 #   redistribute it and/or modify it under the same terms as Perl itself.
 #
-# $FML: Subject.pm,v 1.33 2002/11/26 10:31:35 fukachan Exp $
+# $FML: Subject.pm,v 1.34 2002/12/10 12:00:49 fukachan Exp $
 #
 
 package FML::Header::Subject;
@@ -24,7 +24,7 @@ FML::Header::Subject - manipule the mail header subject
 
 =head1 DESCRIPTION
 
-a collection of functions to manipulate the header subject.
+collection of functions to manipulate the header subject.
 
 =head1 METHODS
 
@@ -52,7 +52,7 @@ sub new
 
 add or rewrite the subject tag for C<$header>.
 This mothod cuts off Re: (reply identifier) in subject: and
-replace the subject with the newer content.
+replace the subject with the newer content e.g. including the ML tag.
 
 =cut
 
@@ -65,15 +65,19 @@ sub rewrite_article_subject_tag
 {
     my ($self, $header, $config, $args) = @_;
     my ($in_code, $out_code);
+
+    # XXX-TODO: need $article_subject_tag expaned already e.g. "\Lmlname\E"
+    # XXX-TODO: we should include this exapansion method within this module?
     my $tag     = $config->{ article_subject_tag };
     my $subject = $header->get('subject');
 
-    # clean up subject
+    # decode MIME encoded string and get charset info if could.
     ($subject, $in_code, $out_code) = $self->decode($subject, $tag);
 
     # cut off Re: Re: Re: ...
     $self->_cut_off_reply(\$subject);
 
+    # XXX-TODO: method-ify _delete_subject_tag() ?
     # de-tag
     $subject = _delete_subject_tag( $subject, $tag );
 
@@ -83,7 +87,7 @@ sub rewrite_article_subject_tag
     use Mail::Message::Encode;
     my $obj = new Mail::Message::Encode;
 
-    # add(prepend) the rewrited tag
+    # add(prepend) the rewrited tag with mime encoding.
     $tag = sprintf($tag, $args->{ id });
     my $new_subject = $tag." ".$subject;
     $new_subject = $obj->encode_mime_string($new_subject, 'base64', $in_code);
@@ -91,10 +95,10 @@ sub rewrite_article_subject_tag
 }
 
 
-# Descriptions:
-#    Arguments: OBJ($self) HASH_REF($args)
-# Side Effects:
-# Return Value: none
+# Descriptions: delete subject tag
+#    Arguments: OBJ($self) STR($subject) STR($tag)
+# Side Effects: none
+# Return Value: STR
 sub clean_up
 {
     my ($self, $subject, $tag) = @_;
@@ -103,10 +107,10 @@ sub clean_up
 }
 
 
-# Descriptions:
-#    Arguments: OBJ($self) HASH_REF($args)
-# Side Effects:
-# Return Value: none
+# Descriptions: exapnd special regexp(s) and mime-decode subject.
+#    Arguments: OBJ($self) STR($subject) STR($tag)
+# Side Effects: none
+# Return Value: ARRAY(STR, STR, STR)
 sub decode
 {
     my ($self, $subject, $tag) = @_;
@@ -119,6 +123,7 @@ sub decode
 	Log($@) if $@;
     }
 
+    # XXX-TODO: care for not Japanese !
     if ($subject =~ /=\?iso-2022-jp\?/i) {
 	$in_code  = 'jis-jp';
 	$out_code = 'euc-jp';
@@ -136,10 +141,10 @@ sub decode
 }
 
 
-# Descriptions:
+# Descriptions: delete subject tag
 #    Arguments: OBJ($self) HASH_REF($args)
-# Side Effects:
-# Return Value: none
+# Side Effects: none
+# Return Value: STR
 sub delete_subject_tag
 {
     my ($self, $subject, $tag) = @_;
@@ -228,6 +233,7 @@ sub is_reply
 
     return 1 if $subject =~ /^\s*Re:/i;
 
+    # XXX-TODO: care for not Japanese string!
     my $pkg = 'Mail::Message::Language::Japanese::Subject';
     eval qq{ require $pkg; $pkg->import();};
     unless ($@) {
@@ -238,7 +244,7 @@ sub is_reply
 }
 
 
-# Descriptions: cut off reply keywords like "Re:"
+# Descriptions: cut off reply keywords like "Re:".
 #    Arguments: OBJ($self) STR_REF($r_subject)
 #               $r_subject is SCALAR REREFENCE to the subject string
 # Side Effects: $r_subject is rewritten
@@ -247,6 +253,7 @@ sub _cut_off_reply
 {
     my ($self, $r_subject) = @_;
 
+    # XXX-TODO: care for not Japanese string!
     my $pkg = 'Mail::Message::Language::Japanese::Subject';
     eval qq{ require $pkg; $pkg->import();};
     unless ($@) {