POD and comments improvement (2024-06)

lib/Sisimai.pm

@@ -8,7 +8,7 @@
 
 sub make {
     # Emulate "rise" method for the backward compatible
     warn ' ***warning: Sisimai->make will be removed at v5.1.0. Use Sisimai->rise instead';
     my $class = shift;
     my $argv0 = shift // return undef; die ' ***error: wrong number of arguments' if scalar @_ % 2;
     my $argv1 = { @_ };
@@ -164,16 +164,16 @@
 
 =head1 DESCRIPTION
 
-C<Sisimai> is a library that decodes complex and diverse bounce emails and outputs the results of
-the delivery failure, such as the reason for the bounce and the recipient email address, in
-structured data. It is also possible to output in JSON format.
+B<Sisimai> is a library that decodes complex and diverse bounce emails and outputs the results of
+the delivery failure, such as the reason for the bounce and the recipient email address, in structured
+data. It is also possible to output in JSON format.
 
 =head1 BASIC USAGE
 
 =head2 C<B<rise(I<'/path/to/mbox'>)>>
 
 C<rise()> method provides the feature for getting decoded data as Perl Hash reference from bounced
-email messages as the following. Beginning with v4.25.6, new accessor origin which keeps the path
+email messages as the following. Beginning with v4.25.6, new accessor C<origin> which keeps the path
 to email file as a data source is available.
 
     use Sisimai;
@@ -232,7 +232,7 @@
     # dump() method also accepts "delivered" and "vacation" option like the following code:
     my $j = Sisimai->dump('/path/to/mbox', 'delivered' => 1, 'vacation' => 1);
 
-=head1 OTHER WAYS TO PARSE
+=head1 OTHER WAYS TO DECODE
 
 =head2 Read email data from STDIN
 
@@ -243,8 +243,8 @@
 
 =head2 Callback Feature
 
-C<c___> (c and three _s, looks like a fishhook) argument of Sisimai->rise and C<Sisimai->dump()> is
-an array reference and is a parameter to receive code references for callback feature. The first
+C<c___> (C<c> and three C<_>s, looks like a fishhook) argument of Sisimai->rise and C<Sisimai->dump()>
+is an array reference and is a parameter to receive code references for callback feature. The first
 element of C<c___> argument is called at C<Sisimai::Message->sift()> for dealing email headers and
 entire message body. The second element of C<c___> argument is called at the end of each email file
 processing. The result generated by the callback method is accessible via C<Sisimai::Fact->catch>.
@@ -298,8 +298,8 @@
                 $e->{'catch'}->{'return-path'} = $1;
             }
 
-            # Save the original email with an additional "X-Sisimai-Parsed:" header to a different PATH.
-            my $a = sprintf("X-Sisimai-Parsed: %d\n", scalar @$fact);
+            # Save the original email with an additional "X-Sisimai-Decoded:" header to a different PATH.
+            my $a = sprintf("X-Sisimai-Decoded: %d\n", scalar @$fact);
             my $p = sprintf("/path/to/another/directory/sisimai-%s.eml", $e->token);
             my $f = IO::File->new($p, 'w');
             my $v = $$mail; $v =~ s/^(From:.+)$/$a$1/m;

lib/Sisimai/ARF.pm

@@ -40,7 +40,7 @@ sub inquire {
     # @param    [Hash] mhead    Message headers of a bounce email
     # @param    [String] mbody  Message body of a bounce email
     # @return   [Hash]          Bounce data list and message/rfc822 part
-    # @return   [undef]         failed to parse or the arguments are missing
+    # @return   [undef]         failed to decode or the arguments are missing
     my $class = shift;
     my $mhead = shift // return undef;
     my $mbody = shift // return undef;
@@ -344,36 +344,32 @@ __END__
 
 =head1 NAME
 
-Sisimai::ARF - Parser class for detecting ARF: Abuse Feedback Reporting Format.
+C<Sisimai::ARF> - Decoder class for detecting ARF: Abuse Feedback Reporting Format.
 
 =head1 SYNOPSIS
 
-Do not use this class directly, use Sisimai::ARF.
-
     use Sisimai::ARF;
     my $v = Sisimai::ARF->inquire($header, $body);
 
 =head1 DESCRIPTION
 
-Sisimai::ARF is a parser for email returned as a Feedback Loop report message.
+C<Sisimai::ARF> is a decoder for email returned as a Feedback Loop report message.
 
 =head1 FEEDBACK TYPES
 
-=head2 B<abuse>
-
-Unsolicited email or some other kind of email abuse.
+=over
 
-=head2 B<fraud>
+=item B<abuse> spam or some other kind of email abuse
 
-Indicates some kind of C<fraud> or C<phishing> activity.
+=item B<fraud> Indicates some kind of fraud or phishing activity
 
-=head2 B<other>
+=item B<virus> report of a virus found in the originating message
 
-Any other feedback that does not fit into other registered types.
+=item B<other> any other feedback that doesn't fit into other types
 
-=head2 B<virus>
+=item B<not-spam> can be used to report an email message that was mistakenly marked as spam
 
-Report of a virus found in the originating message.
+=back
 
 =head1 SEE ALSO
 

lib/Sisimai/Address.pm

@@ -475,13 +475,13 @@ Sisimai::Address - Email address object
 
 =head1 DESCRIPTION
 
-Sisimai::Address provide methods for dealing email address.
+C<Sisimai::Address> provide methods for dealing email address.
 
 =head1 CLASS METHODS
 
 =head2 C<B<is_emailaddress(I<email address>)>>
 
-C<is_emailaddress()> checks the argument is valid email address or not.
+C<is_emailaddress()> method checks the argument is valid email address or not.
 
     print Sisimai::Address->is_emailaddress('[email protected]');  # 1
     print Sisimai::Address->is_emailaddress('neko%example.jp');  # 0
@@ -496,14 +496,15 @@ C<is_emailaddress()> checks the argument is valid email address or not.
 
 =head2 C<B<is_mailerdaemon(I<email address>)>>
 
-C<is_mailerdaemon()> checks the argument is mailer-daemon or not.
+C<is_mailerdaemon()> method checks the argument is B<mailer-daemon> or not.
 
     print Sisimai::Address->is_mailerdaemon('[email protected]');          # 0
     print Sisimai::Address->is_mailerdaemon('[email protected]'); # 1
 
 =head2 C<B<find(I<String>)>>
 
-C<find()> is a new parser for getting only email address from text including email addresses.
+C<find()> method is a new parser for getting only the email address from the given string including
+an email addresses.
 
     my $r = 'Stray cat <[email protected]>, [email protected] (White Cat)',
     my $v = Sisimai::Address->find($r);
@@ -524,7 +525,7 @@ C<find()> is a new parser for getting only email address from text including ema
 
 =head2 C<B<s3s4(I<email address>)>>
 
-C<s3s4()> works Ruleset 3, and 4 of sendmail.cf.
+C<s3s4()> method works Ruleset 3, and 4 of F<sendmail.cf>.
 
     my $r = [
         'Stray cat <[email protected]>',
@@ -538,14 +539,14 @@ C<s3s4()> works Ruleset 3, and 4 of sendmail.cf.
 
 =head2 C<B<expand_verp(I<email address>)>>
 
-C<expand_verp()> gets the original email address from VERP
+C<expand_verp()> method gets the original email address from C<VERP>
 
     my $r = '[email protected]';
     print Sisimai::Address->expand_verp($r); # [email protected]
 
 =head2 C<B<expand_alias(I<email address>)>>
 
-C<expand_alias()> gets the original email address from alias
+C<expand_alias()> method gets the original email address from the alias address
 
     my $r = '[email protected]';
     print Sisimai::Address->expand_alias($r); # [email protected]
@@ -554,44 +555,44 @@ C<expand_alias()> gets the original email address from alias
 
 =head2 C<B<user()>>
 
-C<user()> returns a local part of the email address.
+C<user()> method returns a local part of the email address.
 
     my $v = Sisimai::Address->new({ 'address' => '[email protected]' });
     print $v->user;     # neko
 
 =head2 C<B<host()>>
 
-C<host()> returns a domain part of the email address.
+C<host()> method returns a domain part of the email address.
 
     my $v = Sisimai::Address->new({ 'address' => '[email protected]' });
     print $v->host;     # example.org
 
 =head2 C<B<address()>>
 
-C<address()> returns an email address
+C<address()> method returns an email address
 
     my $v = Sisimai::Address->new({ 'address' => '[email protected]' });
     print $v->address;     # [email protected]
 
 =head2 C<B<verp()>>
 
-C<verp()> returns a VERP email address
+C<verp()> method returns a VERP email address
 
     my $v = Sisimai::Address->new({ 'address' => '[email protected]' });
     print $v->verp;     # [email protected]
     print $v->address;  # [email protected]
 
 =head2 C<B<alias()>>
 
-C<alias()> returns an email address (alias)
+C<alias()> method returns an email address (alias)
 
     my $v = Sisimai::Address->new({ 'address' => '[email protected]' });
     print $v->alias;    # [email protected]
     print $v->address;  # [email protected]
 
 =head2 C<B<name()>>
 
-C<name()> returns a display name
+C<name()> method returns a display name
 
     my $e = '"Neko, Nyaan" <[email protected]>';
     my $r = Sisimai::Address->find($e);
@@ -601,7 +602,7 @@ C<name()> returns a display name
 
 =head2 C<B<comment()>>
 
-C<name()> returns a comment
+C<comment()> method returns a comment
 
     my $e = '"Neko, Nyaan" <neko(nyaan)@example.org>';
     my $v = Sisimai::Address->new(shift Sisimai::Address->find($e)->@*);

lib/Sisimai/DateTime.pm

@@ -414,13 +414,13 @@ Sisimai::DateTime - Date and time utilities
 
 =head1 DESCRIPTION
 
-Sisimai::DateTime provide methods for dealing date and time.
+C<Sisimai::DateTime> provide methods for dealing date and time.
 
 =head1 CLASS METHODS
 
 =head2 C<B<parse(I<Date string>)>>
 
-C<parse()> convert various date format string.
+C<parse()> method converts a various date format string.
 
     my $x = 'Fri, 9 Apr 2004 04:01:03 +0000 (GMT)';
     my $y = '27 Apr 2009 08:08:54 +0900';
@@ -429,7 +429,7 @@ C<parse()> convert various date format string.
 
 =head2 C<B<abbr2tz(I<Abbr>)>>
 
-C<abbr2tz()> convert a time zone abbreviation to 4 digit string of time zone.
+C<abbr2tz()> method converts a time zone abbreviation to 4 digit string of time zone.
 
     print Sisimai::DateTime->abbr2tz('JST');   # +0900
     print Sisimai::DateTime->abbr2tz('UTC');   # +0000