POD for ::Moderate

2 files changed, 122 insertions, 6 deletions

diff --git a/lib/Sietima.pm b/lib/Sietima.pm
index f22e408..6cdf404 100644
--- a/lib/Sietima.pm
+++ b/lib/Sietima.pm
@@ -296,8 +296,19 @@ Returns a hashref describing the command line processing for L<<
 C<App::Spec> >>. L<< C<Sietima::CmdLine> >> uses this to build the
 command line parser.
 
-This base class declares a single sub-command, C<send>, that invokes
-the L<< /C<handle_mail_from_stdin> >> method.
+This base class declares a single sub-command:
+
+=over
+
+=item C<send>
+
+Invokes the L<< /C<handle_mail_from_stdin> >> method.
+
+For example, in a C<.qmail> file:
+
+  |/path/to/sietima send
+
+=back
 
 Roles can extend this to provide additional sub-commands and options.
 
diff --git a/lib/Sietima/Role/SubscriberOnly/Moderate.pm b/lib/Sietima/Role/SubscriberOnly/Moderate.pm
index c0e4a01..750e4be 100644
--- a/lib/Sietima/Role/SubscriberOnly/Moderate.pm
+++ b/lib/Sietima/Role/SubscriberOnly/Moderate.pm
@@ -39,6 +39,16 @@ with 'Sietima::Role::SubscriberOnly',
     'Sietima::Role::WithMailStore',
     'Sietima::Role::WithOwner';
 
+=head1 METHODS
+
+=head2 C<munge_mail_from_non_subscriber>
+
+L<Stores|Sietima::MailStore/store> the email with the C<moderation>
+tag, and forwards it to the L<list
+owner|Sietima::Role::WithOwner/owner>.
+
+=cut
+
 sub munge_mail_from_non_subscriber ($self,$mail) {
     my $id = $self->mail_store->store($mail,'moderation');
     my $notice = Email::Stuffer
@@ -49,6 +59,8 @@ sub munge_mail_from_non_subscriber ($self,$mail) {
         ->attach(
             $mail->as_string,
             content_type => 'message/rfc822',
+            # some clients, most notably Claws-Mail, seem to have
+            # problems with encodings other than this
             encoding => '7bit',
         );
     $self->transport->send($notice->email,{
@@ -58,6 +70,18 @@ sub munge_mail_from_non_subscriber ($self,$mail) {
     return;
 }
 
+=head2 C<resume>
+
+  $sietima->resume($mail_id);
+
+Given an identifier returned when L<storing|Sietima::MailStore/store>
+an email, this method retrieves the email and re-processes it via L<<
+C<ignoring_subscriberonly>|Sietima::Role::SubscriberOnly/ignoring_subscriberonly
+>>. This will make sure that the email is not caught again by the
+subscriber-only filter.
+
+=cut
+
 sub resume ($self,$mail_id) {
     my $mail = $self->mail_store->retrieve_by_id($mail_id);
     $self->ignoring_subscriberonly(
@@ -66,10 +90,33 @@ sub resume ($self,$mail_id) {
     $self->mail_store->remove($mail_id);
 }
 
+=head2 C<drop>
+
+  $sietima->drop($mail_id);
+
+Given an identifier returned when L<storing|Sietima::MailStore/store>
+an email, this method deletes the email from the store.
+
+=cut
+
 sub drop ($self,$mail_id) {
     $self->mail_store->remove($mail_id);
 }
 
+=head2 C<list_mails_in_moderation_queue>
+
+  $sietima->list_mails_in_moderation_queue($sietima_runner);
+
+This method L<retrieves all the
+identifiers|Sietima::MailStore/retrieve_by_tags> of messages tagged
+C<moderation>, and L<prints them out|App::Spec::Runner/out> via the
+L<< C<Sietima::Runner> >> object.
+
+This method is usually invoked from the command line, see L<<
+/C<command_line_spec> >>.
+
+=cut
+
 sub list_mails_in_moderation_queue ($self,$runner,@) {
     my $mails = $self->mail_store->retrieve_by_tags('moderation');
     $runner->out(sprintf 'There are %d messages held for moderation:',scalar($mails->@*));
@@ -83,6 +130,19 @@ sub list_mails_in_moderation_queue ($self,$runner,@) {
     }
 }
 
+=head2 C<show_mail_from_moderation_queue>
+
+  $sietima->show_mail_from_moderation_queue($sietima_runner);
+
+This method L<retrieves the email|Sietima::MailStore/retrieve_by_id>
+of the message requested from the command line, and L<prints it
+out|App::Spec::Runner/out> via the L<< C<Sietima::Runner> >> object.
+
+This method is usually invoked from the command line, see L<<
+/C<command_line_spec> >>.
+
+=cut
+
 sub show_mail_from_moderation_queue ($self,$runner,@) {
     my $id = $runner->parameters->{'mail-id'};
     my $mail = $self->mail_store->retrieve_by_id($id);
@@ -90,12 +150,57 @@ sub show_mail_from_moderation_queue ($self,$runner,@) {
     $runner->out($mail->as_string =~ s{\r\n}{\n}gr);
 }
 
+=head1 MODIFIED METHODS
+
+=head2 C<command_line_spec>
+
+This method adds the following sub-commands for the command line:
+
+=over
+
+=item C<list-held>
+
+  $ sietima list-held
+
+Invokes the L<< /C<list_mails_in_moderation_queue> >> method, printing
+the identifiers of all messages held for moderation.
+
+=item C<show-held>
+
+  $ sietima show-held 32946p6eu7867
+
+Invokes the L<< /C<show_mail_from_moderation_queue> >> method,
+printing one message held for moderation; the identifier is expected
+as a positional parameter.
+
+=item C<resume-held>
+
+  $ sietima resume-held 32946p6eu7867
+
+Invokes the L<< /C<resume> >> method, causing the held message to be
+processed normally; the identifier is expected as a positional
+parameter.
+
+=item C<drop-held>
+
+  $ sietima drop-held 32946p6eu7867
+
+Invokes the L<< /C<drop> >> method, removing the held message; the
+identifier is expected as a positional parameter.
+
+=back
+
+=cut
+
 around command_line_spec => sub ($orig,$self) {
     my $spec = $self->$orig();
 
+    # this allows us to tab-complete identifiers from the shell!
     my $list_mail_ids = sub ($self,$runner,$args) {
         $self->mail_store->retrieve_ids_by_tags('moderation');
     };
+    # a little factoring: $etc->($command_name) generates the spec for
+    # sub-commands that require a mail id
     my $etc = sub($cmd) {
         return (
             summary => "$cmd the given mail, currently held for moderation",
@@ -110,6 +215,10 @@ around command_line_spec => sub ($orig,$self) {
         );
     };
 
+    $spec->{subcommands}{'list-held'} = {
+        op => 'list_mails_in_moderation_queue',
+        summary => 'list all mails currently held for moderation',
+    };
     $spec->{subcommands}{'show-held'} = {
         op => 'show_mail_from_moderation_queue',
         $etc->('show'),
@@ -126,10 +235,6 @@ around command_line_spec => sub ($orig,$self) {
         },
         $etc->('drop'),
     };
-    $spec->{subcommands}{'list-held'} = {
-        op => 'list_mails_in_moderation_queue',
-        summary => 'list all mails currently held for moderation',
-    };
 
     return $spec;
 };