From bc9b7eb76719c6261fbcc807528c9e72434f1dca Mon Sep 17 00:00:00 2001
From: dakkar <dakkar@thenautilus.net>
Date: Sun, 5 Feb 2017 13:25:42 +0000
Subject: POD for ::Types

the coercion SubscriberFromHashRef is documented as having the behaviour
implemented by the *next* commit
---
 lib/Sietima/Types.pm | 125 +++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 125 insertions(+)

diff --git a/lib/Sietima/Types.pm b/lib/Sietima/Types.pm
index 39b9f8e..3288972 100644
--- a/lib/Sietima/Types.pm
+++ b/lib/Sietima/Types.pm
@@ -12,10 +12,67 @@ use Type::Library
                    Subscriber SubscriberFromAddress SubscriberFromStr SubscriberFromHashRef
                    Transport MailStore MailStoreFromHashRef);
 
+=head1 NAME
+
+Sietima::Types - type library for Sietima
+
+=head1 DESCRIPTION
+
+This module is a L<< C<Type::Library> >>. It declares a few type
+constraints nad coercions.
+
+=head1 TYPES
+
+=head2 C<SietimaObj>
+
+An instance of L<< C<Sietima> >>.
+
+=cut
+
 class_type SietimaObj, { class => 'Sietima' };
 
+=head2 C<EmailMIME>
+
+An instance of L<< C<Email::MIME> >>.
+
+=cut
+
 class_type EmailMIME, { class => 'Email::MIME' };
+
+=head2 C<Transport>
+
+An object that consumes the role L<< C<Email::Sender::Transport> >>.
+
+=cut
+
 role_type Transport, { role => 'Email::Sender::Transport' };
+
+=head2 C<MailStore>
+
+An object that consumes the role L<< C<Sietima::MailStore> >>.
+
+Coercions:
+
+=over
+
+=item C<MailStoreFromHashRef>
+
+  has store => ( isa => MailStore->plus_coercions(MailStoreFromHashRef) );
+
+Using this coercion, a hashref of the form:
+
+  {
+    class => 'Some::Store::Class',
+    %constructor_args,
+  }
+
+will be converted into an instance of C<Some::Store::Class> built with
+the C<%constructor_args>.
+
+=back
+
+=cut
+
 role_type MailStore, { role => 'Sietima::MailStore' };
 
 declare_coercion MailStoreFromHashRef,
@@ -24,11 +81,38 @@ declare_coercion MailStoreFromHashRef,
        Module::Runtime::use_module(delete $_->{class})->new($_);
      };
 
+=head2 C<Address>
+
+An instance of L<< C<Email::Address> >>.
+
+Coercions:
+
+=over
+
+=item C<AddressFromStr>
+
+  has address => ( isa => Address->plus_coercions(AddressFromStr) );
+
+Using this coercion, a string will be parsed into an L<<
+C<Email::Address> >>. If the string contains more than one address,
+only the first one will be used.
+
+=back
+
+=cut
+
 class_type Address, { class => 'Email::Address' };
 declare_coercion AddressFromStr,
     to_type Address, from Str,
     q{ (Email::Address->parse($_))[0] };
 
+=head2 C<TagName>
+
+A string composed exclusively of "word" (C</\w/>) characters. Used by
+L<mail stores|Sietima::MailStore> to tag messages.
+
+=cut
+
 declare TagName, as Str,
     where { /\A\w+\z/ },
     inline_as sub($constraint,$varname,@){
@@ -36,12 +120,53 @@ declare TagName, as Str,
             .qq{ && ($varname =~/\\A\\w+\\z/) };
     };
 
+=head2 C<Message>
+
+An instance of L<< C<Sietima::Message> >>.
+
+=cut
+
 class_type Message, { class => 'Sietima::Message' };
 
+=head2 C<Subscriber>
+
+An instance of L<< C<Sietima::Subscriber> >>.
+
+Coercions:
+
+=over
+
+=item C<SubscriberFromAddress>
+
+  has sub => ( isa => Subscriber->plus_coercions(SubscriberFromAddress) );
+
+Using this coercion, an L<< C<Email::Address> >> will be converted
+into a subscriber that has that address as its primary.
+
+=item C<SubscriberFromStr>
+
+  has sub => ( isa => Subscriber->plus_coercions(SubscriberFromStr) );
+
+Using this coercion, a string will be converted into a subscriber that
+has the first address parsed from that string as its primary.
+
+=item C<SubscriberFromHashRef>
+
+  has sub => ( isa => Subscriber->plus_coercions(SubscriberFromHashRef) );
+
+Using this coercion, a hashref will be converted into a subscriber by
+passing it to the constructor.
+
+=back
+
+=cut
+
 class_type Subscriber, { class => 'Sietima::Subscriber' };
+
 declare_coercion SubscriberFromAddress,
     to_type Subscriber, from Address,
     q{ Sietima::Subscriber->new(raw_address=>$_) };
+
 declare_coercion SubscriberFromStr,
     to_type Subscriber, from Str,
     q{ Sietima::Subscriber->new(raw_address=>(Email::Address->parse($_))[0]) };
-- 
cgit v1.2.3