POD for some roles

5 files changed, 149 insertions, 0 deletions

diff --git a/lib/Sietima/Role/AvoidDups.pm b/lib/Sietima/Role/AvoidDups.pm
index 598d57b..964c413 100644
--- a/lib/Sietima/Role/AvoidDups.pm
+++ b/lib/Sietima/Role/AvoidDups.pm
@@ -4,6 +4,23 @@ use Sietima::Policy;
 use Email::Address;
 use namespace::clean;
 
+=head1 NAME
+
+Sietima::Role::AvoidDups - prevent people from receiving the same message multiple times
+
+=head1 SYNOPSIS
+
+  my $sietima = Sietima->with_traits('AvoidDups')->new(\%args);
+
+=head1 DESCRIPTION
+
+A L<< C<Sietima> >> list with this role applied will not send a
+message to a subscriber, if that subscriber is already mentioned in
+the C<To:> or C<Cc:> header fields, because they can be assumed to be
+already receiving the message directly from the sender.
+
+=cut
+
 around subscribers_to_send_to => sub ($orig,$self,$mail) {
     my @already_receiving = map {
         Email::Address->parse($_)
diff --git a/lib/Sietima/Role/Debounce.pm b/lib/Sietima/Role/Debounce.pm
index 8df53a5..882d982 100644
--- a/lib/Sietima/Role/Debounce.pm
+++ b/lib/Sietima/Role/Debounce.pm
@@ -3,6 +3,24 @@ use Moo::Role;
 use Sietima::Policy;
 use namespace::clean;
 
+=head1 NAME
+
+Sietima::Role::Debounce - avoid mail loops
+
+=head1 SYNOPSIS
+
+  my $sietima = Sietima->with_traits('Debounce')->new(\%args);
+
+=head1 DESCRIPTION
+
+A L<< C<Sietima> >> list with this role applied will mark each message
+with a C<X-Been-There> header, and will not handle any messages that
+have that same header. This prevents messages bounced by other
+services from being looped between the mailing list and those other
+services.
+
+=cut
+
 my $been_there = 'X-Been-There';
 
 around munge_mail => sub ($orig,$self,$incoming_mail) {
diff --git a/lib/Sietima/Role/Headers.pm b/lib/Sietima/Role/Headers.pm
index 3a91c6f..f73db93 100644
--- a/lib/Sietima/Role/Headers.pm
+++ b/lib/Sietima/Role/Headers.pm
@@ -5,6 +5,48 @@ use Sietima::Policy;
 use Types::Standard qw(Str);
 use namespace::clean;
 
+=head1 NAME
+
+Sietima::Role::Headers - adds standard list-related headers to messages
+
+=head1 SYNOPSIS
+
+  my $sietima = Sietima->with_traits('Headers')->new({
+   %args,
+   name => $name_of_the_list,
+  });
+
+=head1 DESCRIPTION
+
+A L<< C<Sietima> >> list with this role applied will add, to each
+outgoing message, the set of headers defined in RFC 2919 and RFC 2369.
+
+This role uses the L<< C<list_addresses>|Sietima/list_addresses >>
+method to determine what headers to add.
+
+If the C<name> attribute is set, a C<List-Id:> header will be added,
+with a value built out of the name and the C<<
+$self->list_addresses->{return_path} >> value (which is normally the
+same as the L<< C<return_path>|Sietima/return_path >> attribute).
+
+Other C<List-*:> headers are built from the other values in the
+C<list_addresses> hashref. Those values can either be L<<
+C<Email::Address> >> objects (in which case the header will have a
+C<mailto:> URI as value) or strings (which will be used literally for
+the value of the header).
+
+=head1 ATTRIBUTES
+
+=head2 C<name>
+
+Optional string, the name of the mailing list. If this attribute is
+set, a C<List-Id:> header will be added, with a value built out of the
+name and the C<< $self->list_addresses->{return_path} >> value (which
+is normally the same as the L<< C<return_path>|Sietima/return_path >>
+attribute).
+
+=cut
+
 has name => (
     isa => Str,
     is => 'ro',
diff --git a/lib/Sietima/Role/NoMail.pm b/lib/Sietima/Role/NoMail.pm
index 84d7d9b..5f6dd77 100644
--- a/lib/Sietima/Role/NoMail.pm
+++ b/lib/Sietima/Role/NoMail.pm
@@ -3,6 +3,28 @@ use Moo::Role;
 use Sietima::Policy;
 use namespace::clean;
 
+=head1 NAME
+
+Sietima::Role::NoMail - don't send mail to those who don't want it
+
+=head1 SYNOPSIS
+
+  my $sietima = Sietima->with_traits('NoMail')->new({
+   %args,
+   subscribers => [
+    { primary => 'write-only@example.com', prefs => { wants_mail => 0 } },
+    @other_subscribers,
+   ],
+  });
+
+=head1 DESCRIPTION
+
+A L<< C<Sietima> >> list with this role applied will not send messages
+to subscribers that have the C<wants_mail> preference set to a false
+value.
+
+=cut
+
 around subscribers_to_send_to => sub ($orig,$self,$mail) {
     return [
         grep { $_->prefs->{wants_mail} // 1 }
diff --git a/lib/Sietima/Role/ReplyTo.pm b/lib/Sietima/Role/ReplyTo.pm
index 583b1de..5962451 100644
--- a/lib/Sietima/Role/ReplyTo.pm
+++ b/lib/Sietima/Role/ReplyTo.pm
@@ -6,12 +6,62 @@ use Sietima::Types qw(Address AddressFromStr);
 use List::AllUtils qw(part);
 use namespace::clean;
 
+=head1 NAME
+
+Sietima::Role::ReplyTo - munge the C<Reply-To> header
+
+=head1 SYNOPSIS
+
+  my $sietima = Sietima->with_traits('ReplyTo')->new({
+    %args,
+    return_path => 'list-bounce@example.com',
+    munge_reply_to => 1,
+    post_address => 'list@example.com',
+    subscribers => [
+      { primary => 'special@example.com', prefs => { munge_reply_to => 0 } },
+      @other_subscribers,
+    ],
+  });
+
+=head1 DESCRIPTION
+
+A L<< C<Sietima> >> list with this role applied will, on request, set
+the C<Reply-To:> header to the value of the L<< /C<post_address> >>
+attribute.
+
+This behaviour can be selected both at the list level (with the L<<
+/C<munge_reply_to> >> attribute) and at the subscriber level (with the
+C<munge_reply_to> preference). By default, the C<Reply-To:> header is
+not touched.
+
+=head1 ATTRIBUTES
+
+=head2 C<munge_reply_to>
+
+Optional boolean, defaults to false. If set to a true value, all
+messages will have their C<Reply-To:> header set to the value of the
+L<< /C<post_address> >> attribute. This setting can be overridden by
+individual subscribers with the C<munge_reply_to> preference.
+
+=cut
+
 has munge_reply_to => (
     is => 'ro',
     isa => Bool,
     default => 0,
 );
 
+=head2 C<post_address>
+
+An L<< C<Email::Address> >> object, defaults to the value of the L<<
+C<return_path>|Sietima/return_path >> attribute. This is the address
+that the mailing list receives messages at.
+
+This role extends the L<< C<list_addresses>|Sietima/list_addresses >>
+method to include this address.
+
+=cut
+
 has post_address => (
     is => 'lazy',
     isa => Address,