From 564c0667e00820734fd2667911862dbc72ef72a6 Mon Sep 17 00:00:00 2001
From: dakkar <dakkar@thenautilus.net>
Date: Fri, 3 Feb 2017 20:28:40 +0000
Subject: POD for ::Subscriber

---
 lib/Sietima/Subscriber.pm | 67 +++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 67 insertions(+)

(limited to 'lib')

diff --git a/lib/Sietima/Subscriber.pm b/lib/Sietima/Subscriber.pm
index 68f119b..649b2e5 100644
--- a/lib/Sietima/Subscriber.pm
+++ b/lib/Sietima/Subscriber.pm
@@ -8,6 +8,28 @@ use Email::Address;
 use List::AllUtils qw(any);
 use namespace::clean;
 
+=head1 NAME
+
+Sietima::Subscriber - a subscriber to a mailing list
+
+=head1 DESCRIPTION
+
+This class holds the primary email address for a mailing list
+subscriber, together with possible aliases and preferences.
+
+=head1 ATTRIBUTES
+
+All attributes are read-only.
+
+=head2 C<raw_address>
+
+Required L<< C<Email::Address> >> object, coercible from a string.
+
+This is the primary address for the subscriber, the one where they
+will receive messages from the mailing list.
+
+=cut
+
 has raw_address => (
     isa => Address,
     is => 'ro',
@@ -16,6 +38,18 @@ has raw_address => (
     handles => [qw(address name original)],
 );
 
+=head2 C<aliases>
+
+Arrayref of L<< C<Email::Address> >> objects, each coercible from a
+string. Defaults to an empty arrayref.
+
+These are secondary addresses that the subscriber may write
+from. Subscriber-only mailing lists should accept messages from any of
+these addresses as if they were from the primary. The L<< /C<match> >>
+simplifies that task.
+
+=cut
+
 my $address_array = ArrayRef[
     Address->plus_coercions(
         AddressFromStr
@@ -28,12 +62,34 @@ has aliases => (
 );
 sub _build_aliases { +[] }
 
+=head2 C<prefs>
+
+A hashref. Various preferences that may be interpreted by Sietima
+roles. Defaults to an empty hashref.
+
+=cut
+
 has prefs => (
     isa => HashRef,
     is => 'ro',
     default => sub { +{} },
 );
 
+=head1 METHODS
+
+=head2 C<match>
+
+  if ($subscriber->match($address)) { ... }
+
+Given a L<< C<Email::Address> >> object (or a string), this method
+returns true if the address is equivalent to the
+L<primary|/raw_address> or any of the L</aliases>.
+
+This method should be used to determine whether an address belongs to
+a subscriber.
+
+=cut
+
 sub match {
     # we can't use the sub signature here, because we need the
     # coercion
@@ -44,4 +100,15 @@ sub match {
         $self->raw_address, $self->aliases->@*;
 }
 
+=head2 C<address>
+
+=head2 C<name>
+
+=head2 C<original>
+
+These methods delegate to L<< C<Email::Address> >>'s methods of the
+same name, invoked on the L<primary address|/raw_address>.
+
+=cut
+
 1;
-- 
cgit v1.2.3