POD for ::Message

1 files changed, 57 insertions, 0 deletions

diff --git a/lib/Sietima/Message.pm b/lib/Sietima/Message.pm
index 9d8ef61..181575f 100644
--- a/lib/Sietima/Message.pm
+++ b/lib/Sietima/Message.pm
@@ -10,12 +10,50 @@ use Sietima::Subscriber;
 use Email::MIME;
 use namespace::clean;
 
+=head1 NAME
+
+Sietima::Message - an email message with an envelope
+
+=head1 SYNOPSIS
+
+  use Sietima::Message;
+
+  my $msg = Sietima::Message->new({
+    mail => $email_mime_object,
+    from => 'sender@example.com',
+    to => [ 'recipient@example.com', 'also@example.com' ],
+  });
+
+=head1 DESCRPITON
+
+This class pairs a L<< C<Email::MIME> >> object with its
+envelope. Objects of this class are usually generated by L<<
+C<Sietima::munge_mail>|Sietima/munge_mail >>, and consumed by L<<
+C<Sietima::send_message>|Sietima/send_message >>.
+
+=head1 ATTRIBUTES
+
+All attributes are read-only and required.
+
+=head2 C<mail>
+
+An L<< C<Email::MIME> >> object, representing the message.
+
+=cut
+
 has mail => (
     is => 'ro',
     isa => EmailMIME,
     required => 1,
 );
 
+=head2 C<from>
+
+An L<< C<Email::Address> >> object, coercible from a string,
+representing the sender.
+
+=cut
+
 has from => (
     is => 'ro',
     isa => Address,
@@ -23,6 +61,14 @@ has from => (
     required => 1,
 );
 
+=head2 C<to>
+
+An arrayref of L<< C<Sietima::Subscriber> >> objects, each coercible
+from a string or an L<< C<Email::Address> >> object, representing the
+recipients.
+
+=cut
+
 my $subscriber_array = ArrayRef[
     Subscriber->plus_coercions(
         SubscriberFromStr,
@@ -36,6 +82,17 @@ has to => (
     required => 1,
 );
 
+=head1 METHODS
+
+=head2 C<envelope>
+
+  my %envelope = $message->envelope->%*;
+
+Returns a hashref with envelope data, suitable for use with L<<
+C<Email::Sender::Transport::send>|Email::Sender::Transport/send >>.
+
+=cut
+
 sub envelope ($self) {
     return {
         from => $self->from,