Skip to content

Commit

Permalink
Merge pull request #527 from sisimai/pod-improvement-7e86
Browse files Browse the repository at this point in the history
POD and comments improvement (2024-06)
  • Loading branch information
azumakuniyuki authored Jun 16, 2024
2 parents 665817b + 7c78f33 commit 87d1697
Show file tree
Hide file tree
Showing 135 changed files with 1,104 additions and 1,359 deletions.
18 changes: 9 additions & 9 deletions lib/Sisimai.pm
Original file line number Diff line number Diff line change
Expand Up @@ -164,16 +164,16 @@ Sisimai - Mail Analyzing Interface for bounce mails.
=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;
Expand Down Expand Up @@ -232,7 +232,7 @@ messages like the following code:
# 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
Expand All @@ -243,8 +243,8 @@ C<rise()> method like following command:
=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>.
Expand Down Expand Up @@ -298,8 +298,8 @@ dealing each email file.
$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;
Expand Down
24 changes: 10 additions & 14 deletions lib/Sisimai/ARF.pm
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand Down Expand Up @@ -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
Expand Down
29 changes: 15 additions & 14 deletions lib/Sisimai/Address.pm
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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);
Expand All @@ -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]>',
Expand All @@ -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]
Expand All @@ -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);
Expand All @@ -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)->@*);
Expand Down
6 changes: 3 additions & 3 deletions lib/Sisimai/DateTime.pm
Original file line number Diff line number Diff line change
Expand Up @@ -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';
Expand All @@ -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
Expand Down
Loading

0 comments on commit 87d1697

Please sign in to comment.