Commit 169bb941 authored by sikeda's avatar sikeda
Browse files

[dev] Completed documentation of several modules.

git-svn-id: https://subversion.renater.fr/sympa/branches/sympa-6.2-branch@11726 05aa8bb8-cd2b-0410-b1d7-8918dfa770ce
parent c1d1a5bb
......@@ -186,11 +186,12 @@ Sympa::Alarm - Spool on memory for listmaster notification
=head1 SYNOPSIS
use Sympa::Alarm;
Sympa::Alarm->instance->store($message, $rcpt, $operation);
Sympa::Alarm->instance->flush();
Sympa::Alarm->instance->flush(purge => 1);
my $alarm = Sympa::Alarm->instance;
$alarm->store($message, $rcpt, $operation);
$alarm->flush();
$alarm->flush(purge => 1);
=head1 DESCRIPTION
......
......@@ -390,7 +390,12 @@ Sympa::Bulk - Spool for bulk sending
=head1 SYNOPSIS
TBD
use Sympa::Bulk;
my $bulk = Sympa::Bulk->new;
$bulk->store($message, ['user@dom.ain', 'user@other.dom.ain']);
my ($message, $handle) = $bulk->next;
=head1 DESCRIPTION
......@@ -511,11 +516,11 @@ Scalar, scalarref or arrayref, for SMTP "RCPT TO:" field(s).
=item original =E<gt> $original
TBD
If the message was decrypted, stores original encrypted form.
=item tag =E<gt> $tag
TBD
TBD.
=back
......
......@@ -1213,10 +1213,16 @@ Each definition is hashref containig following keys:
=item fields
See below.
=item doc
Description of the table.
=item order
TBD.
=back
C<fields> item is hasref which may contain following items.
......@@ -1225,14 +1231,14 @@ C<fields> item is hasref which may contain following items.
=item struct
Column data types. Types are based on MySQL.
Column data types. Definitions are based on MySQL.
Following types are recognized:
=over
=item varchar(X)
=item varchar(I<length>)
Text with length upto X. X must be lower than 2^16 - 2.
Text with length upto I<length>. I<length> must be lower than 2^16 - 2.
=item int(1)
......@@ -1242,9 +1248,9 @@ Boolean, 1 or 0.
Unix time (a.k.a. "epoch").
=item int(X)
=item int(I<cols>)
Integer with columns upto X, -2^31 to 2^31 - 1.
Integer with columns upto I<cols>, with its value from -2^31 to 2^31 - 1.
=item tinyint
......@@ -1286,15 +1292,16 @@ Binary data with length upto 2^24 - 3 o.
=item doc
XXX
Description of the field.
=item primary
XXX
If this is true, primary key consists of this field.
=item not_null
XXX
If this is true, Null value is not allowed.
Note that fields included in primary key always don't allow Null value.
=back
......@@ -1308,17 +1315,17 @@ converted according to types.
=item not_null ()
I<Function>.
XXX
TBD.
=item autoincrement ()
I<Function>.
XXX
TBD.
=item primary ()
I<Function>.
XXX
TBD.
=back
......
......@@ -714,6 +714,14 @@ __END__
Sympa::Language - Handling languages and locales
=head1 SYNOPSIS
use Sympa::Language;
my $language = Sympa::Language->instance;
$language->set_lang('zh-TW', 'zh', 'en');
print $language->gettext('Lorem ipsum dolor sit amet.');
=head1 DESCRIPTION
This package provides interfaces for i18n (internationalization) of Sympa.
......@@ -978,7 +986,7 @@ Note that the language actually set may not be identical to the parameter
$lang, even when latter has been canonicalized.
The language tag C<'en'> is special:
it is used to set C<'C'> locale and will succeed always.
It is used to set C<'C'> locale and will succeed always.
Note:
This function of Sympa 6.2a or earlier returned old style "locale" names.
......@@ -1023,7 +1031,26 @@ If it is not known, returns default language tag.
=item dgettext ( $domain, $msgid )
I<Instance method>.
XXX @todo doc
Returns the translation of given string using NLS catalog in domain $domain.
Note that L</set_lang>() must be called in advance.
Parameter:
=over
=item $domain
gettext domain.
=item $msgid
gettext message ID.
=back
Returns:
Translated string or, if it wasn't found, original string.
=item gettext ( $msgid )
......@@ -1110,7 +1137,33 @@ Translated and formatted string.
=item maketext ( $textdomain, $template, $args, ... )
I<Instance method>.
XXX @todo doc
At first, translates $template argument using L</gettext>().
Then replaces placeholders (C<%1>, C<%2>, ...) in template with arguments.
Numeric arguments will be formatted using appropriate locale, if any:
Typically, the decimal point specific to each locale may be used.
Parameters:
=over
=item $textdomain
NLS domain to be used for searching catalogs.
=item $template
Template string which may include placeholders.
=item $args, ...
Arguments corresponding to placeholders.
=back
Returns:
Translated and replaced string.
=back
......
......@@ -2028,7 +2028,7 @@ sub distribute_msg {
## Add RFC5064 Archived-At SMTP header field
$self->add_list_header($message, 'archived_at');
## Remove outgoing header fileds
## Remove outgoing header fields
## Useful to remove some header fields that Sympa has set
if ($self->{'admin'}{'remove_outgoing_headers'}) {
foreach my $field (@{$self->{'admin'}{'remove_outgoing_headers'}}) {
......@@ -7971,7 +7971,8 @@ sub sync_include_ca {
$users{$user->{'email'}} = $user->{'custom_attribute'};
}
foreach my $type ('include_sql_ca','include_ldap_ca','include_ldap_2level_ca') {
foreach my $type ('include_sql_ca', 'include_ldap_ca',
'include_ldap_2level_ca') {
foreach my $tmp_incl (@{$admin->{$type}}) {
## Work with a copy of admin hash branch to avoid including
## temporary variables into the actual admin hash.[bug #3182]
......
......@@ -294,6 +294,15 @@ __END__
Sympa::Mailer - Store messages to sendmail
=head1 SYNOPSIS
use Sympa::Mailer;
my $mailer = Sympa::Mailer->instance;
$mailer->store($message, ['user1@dom.ain', user2@other.dom.ain']);
$mailer->reaper;
=head1 DESCRIPTION
L<Sympa::Mailer> implements the class to invoke sendmail processes and
......@@ -376,7 +385,7 @@ Otherwise C<undef>.
=head2 Attributes
L<Sympa::Mailer> instance has following attributes:
L<Sympa::Mailer> instance may have following attributes:
=over
......@@ -386,7 +395,8 @@ If true value is set, each invokation of sendmail process will be logged.
=item {redundancy}
TBD.
Positive integer.
If set, maximum number of invokation of sendmail is divided by this value.
=back
......
......@@ -28,6 +28,11 @@
Message - Mail message embedding for internal use in Sympa
=head1 SYNOPSYS
use Sympa::Message;
my $message = Sympa::Message->new($serialized, context => $list);
=head1 DESCRIPTION
While processing a message in Sympa, we need to link informations to the
......@@ -945,7 +950,9 @@ sub to_string {
=item add_header ( $field, $value, [ $index ] )
I<Instance method>.
XXX
Adds a header field named $field with body $value.
If $index is given, the field will be inserted at the place it indicates:
If it is C<0>, the field will be prepended.
=back
......@@ -962,7 +969,7 @@ sub add_header {
=item delete_header ( $field, [ $index ] )
I<Instance method>.
XXX
Deletes all occurences of the header field named $field.
=back
......@@ -979,7 +986,7 @@ sub delete_header {
=item replace_header ( $field, $value, [ $index ] )
I<Instance method>.
XXX
Replaces header fields named $field with $value.
=back
......@@ -1049,10 +1056,11 @@ sub check_spam_status {
=over
=item dkim_sign ( )
=item dkim_sign ( dkim_d =E<gt> $d, [ dkim_i =E<gt> $i ],
dkim_selector =E<gt> $selector, dkim_privatekey =E<gt> $privatekey )
I<Instance method>.
XXX
Adds DKIM signature to the message.
=back
......@@ -1201,7 +1209,8 @@ sub check_dkim_signature {
=item remove_invalid_dkim_signature ( )
I<Instance method>.
XXX
Verify DKIM signatures included in the message,
and if any of them are invalid, remove them.
=back
......@@ -1338,7 +1347,9 @@ sub as_string {
=item body_as_string ( )
I<Instance method>.
XXX
Gets body of the message as string.
Note that the result won't be decoded.
=back
......@@ -1354,7 +1365,9 @@ sub body_as_string {
=item header_as_string ( )
I<Instance method>.
XXX
Gets header part of the message as string.
Note that the result won't be decoded nor unfolded.
=back
......@@ -1928,7 +1941,9 @@ sub smime_encrypt {
=item smime_sign ( )
I<Instance method>.
XXX
Adds S/MIME signature to the message.
Signing key is taken from what stored in list directory.
Parameters:
......@@ -2031,7 +2046,8 @@ sub smime_sign {
=item check_smime_signature ( )
I<Instance method>.
XXX
Verifys S/MIME signature of the message,
and if verification succeeded, sets {smime_signed} item true.
Parameters:
......@@ -2492,7 +2508,11 @@ sub personalize_text {
=item prepare_message_according_to_mode ( $mode, $list )
I<Instance method>.
XXX
Transforms the message according to reception mode:
C<'mail'>, C<'notice'>, C<'txt'> or C<'html'>.
By C<'nomail'>, C<'digest'>, C<'digestplain'> or C<'summary'> mode,
the message is not modified.
=back
......@@ -3137,7 +3157,7 @@ string
# More Note: Latter behavior above will give expected result only if
# contents of sub-messages are US-ASCII or ISO-8859-1. In other cases
# customized templates (if any) should be modified so that they have
# appropriate `X-Sympa-Attach:' header fileds.
# appropriate `X-Sympa-Attach:' header fields.
#
# Sub-messages are gathered from template context paramenters.
......@@ -3383,7 +3403,7 @@ sub _as_singlepart {
=item check_virus_infection ()
I<Instance method>.
XXX
Checks the message using anti-virus plugin, if configuration requests it.
Returns:
......@@ -4215,7 +4235,33 @@ See also {envelope_sender} above.
Shelved processing.
Hashref with multiple items.
XXX
Currently these items are available:
=over
=item dkim_sign =E<gt> 1
Adding DKIM signature.
=item merge =E<gt> 1
Personalizing.
=item smime_encrypt =E<gt> 1
Adding S/MIME encryption.
=item smime_sign =E<gt> 1
Adding S/MIME signature.
=item tracking =E<gt> C<dsn>|C<mdn>|C<r>|C<w>|C<verp>
Requesting tracking feature including VERP.
=back
This is used by bulk spool.
=item {spam_status}
......@@ -4224,8 +4270,6 @@ This is set by L</check_spam_status>() method.
=back
XXX
=head2 Serialization
L<Sympa::Message> object includes number of slots as hash items:
......
......@@ -78,8 +78,7 @@ sub next {
unless ($self->{_metadatas}) {
my $dh;
unless (opendir $dh, $self->{directory}) {
die sprintf 'Cannot open dir %s: %s', $self->{directory},
$ERRNO;
die sprintf 'Cannot open dir %s: %s', $self->{directory}, $ERRNO;
}
$self->{_metadatas} = [
sort grep {
......@@ -151,13 +150,9 @@ sub store {
$message->{date} = time unless defined $message->{date};
my $marshalled = tools::store_spool(
$self->{directory},
$message,
'%d.%f.%s@%s,%ld,%d',
[qw(date TIME localpart domainpart PID RAND) ],
%options
);
my $marshalled =
tools::store_spool($self->{directory}, $message, '%d.%f.%s@%s,%ld,%d',
[qw(date TIME localpart domainpart PID RAND)], %options);
return unless $marshalled;
Log::do_log('notice', 'Message %s is stored into archive spool as <%s>',
......@@ -176,7 +171,12 @@ Sympa::Spool::Archive - Spool for messages waiting for archiving.
=head1 SYNOPSIS
TBD
use Sympa::Spool::Archive;
my $spool = Sympa::Spool::Archive->new;
$spool->store($message);
my ($message, $handle) = $spool->next;
=head1 DESCRIPTION
......@@ -280,7 +280,7 @@ Unix time in floating point number when the message was stored.
=item original =E<gt> $original
TBD
If the message was decrypted, stores original encrypted form.
=back
......
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment