[swiftsieve] [PATCH] Add synopses to the documentation, and generally clean it up.

[Vsevolod Kozlov]

---
 lib/App/Swiftsieve.pm                 |   19 ++++++++++++-------
 lib/App/Swiftsieve/Sieve.pm           |   20 +++++++++++++++-----
 lib/App/Swiftsieve/Sieve/Condition.pm |   24 +++++++++++++++++-------
 lib/App/Swiftsieve/Sieve/Rule.pm      |   23 ++++++++++++++++-------
 lib/App/Swiftsieve/Sieve/Script.pm    |   23 ++++++++++++++++++-----
 lib/App/Swiftsieve/Util.pm            |    5 +++++
 6 files changed, 83 insertions(+), 31 deletions(-)

diff --git a/lib/App/Swiftsieve.pm b/lib/App/Swiftsieve.pm
index 0c74753..e993515 100644
--- a/lib/App/Swiftsieve.pm
+++ b/lib/App/Swiftsieve.pm
@@ -37,7 +37,10 @@ use User::grent;
 
 App::Swiftsieve - Manage Sieve scripts in your webbrowser
 
-=head1 DESCRIPTION
+=head1 RUNMODES
+
+App::Swiftsieve is a L<CGI::Application> - see its documentation for more
+information.
 
 =over
 
@@ -173,7 +176,8 @@ sub _render_template {
 
 =item B<fatal_error>
 
-Runmode for displaying fatal errors
+Runmode for displaying fatal errors.
+
 =cut
 sub fatal_error : ErrorRunmode {
     my($self, $error) = @_;
@@ -198,7 +202,7 @@ sub login : Runmode {
 
 =item B<index>
 
-Prints a list of the script and a box for creating new scripts
+Prints a list of the script and a box for creating new scripts.
 
 =cut
 sub index : StartRunmode {
@@ -215,7 +219,8 @@ sub index : StartRunmode {
 
 =item B<admin>
 
-Presents a form for admins to enter a user account
+Presents a form for admins to enter a user account.
+
 =cut
 sub admin : Runmode {
     my($self) = @_;
@@ -273,7 +278,7 @@ sub _check_disabled_conditions {
 
 =item B<script>
 
-Renders the form for editing scripts or saves a script
+Renders the form for editing scripts or saves a script.
 
 =cut
 sub script : Runmode {
@@ -324,7 +329,7 @@ sub script : Runmode {
 
 =item B<activate>
 
-Activates a given script
+Activates a given script.
 
 =cut
 sub activate : Runmode {
@@ -338,7 +343,7 @@ sub activate : Runmode {
 
 =item B<delete>
 
-Deletes a given script
+Deletes a given script.
 
 =cut
 sub delete : Runmode {
diff --git a/lib/App/Swiftsieve/Sieve.pm b/lib/App/Swiftsieve/Sieve.pm
index 3cee37c..4b3e008 100644
--- a/lib/App/Swiftsieve/Sieve.pm
+++ b/lib/App/Swiftsieve/Sieve.pm
@@ -27,11 +27,21 @@ App::Swiftsieve::Sieve - Net::Sieve wrapper used in Swiftsieve
 
 =head1 SYNOPSIS
 
+    my $sieve = new App::Swiftsieve::Sieve (
+        server => "127.0.0.1",
+        user => "myuser",
+        password => "foobar",
+    );
+
+    $sieve->put("my_script", $script);
+
+=head1 DESCRIPTION
+
 App::Swiftsieve::Sieve is a convenience wrapper around Net::Sieve. Its
 most imporant task is to convert the scripts returned from the server into
 App::Swiftsieve::Sieve::Script objects.
 
-=head1 DESCRIPTION
+=head1 METHODS
 
 =over
 
@@ -87,7 +97,7 @@ sub get {
 
 =item B<put($script_name, $script)>
 
-Writes the given script to the server
+Writes the given script to the server.
 
 =cut
 sub put {
@@ -99,7 +109,7 @@ sub put {
 
 =item B<activate($script_name)>
 
-Sets the given script as the active script
+Sets the given script as the active script.
 
 =cut
 sub activate {
@@ -123,8 +133,8 @@ sub delete {
 
 =item B<scripts()>
 
-Returns two arguments, a reference to an array of script names
-and a string containing the active script.
+Returns two arguments, a reference to an array of script names and a string
+containing the active script.
 
 =cut
 sub scripts {
diff --git a/lib/App/Swiftsieve/Sieve/Condition.pm b/lib/App/Swiftsieve/Sieve/Condition.pm
index 9850861..53826e5 100644
--- a/lib/App/Swiftsieve/Sieve/Condition.pm
+++ b/lib/App/Swiftsieve/Sieve/Condition.pm
@@ -30,14 +30,24 @@ App::Swiftsieve::Sieve::Condition - Handle a limited subset of Sieve
 
 =head1 SYNOPSIS
 
-Conditions are part of Sieve's rules. Swiftsieve simplifies a condition to having
-a haystack, a needle and an operator.
+    my $condition = new App::Swiftsieve::Sieve::Condition();
 
-To get the text representation of this condition, ready for the Sieve server, you
-should call the write() method.
+    $condition->haystack("size");
+    $condition->operator("over");
+    $condition->needle("100");
+
+    print $condition->write();
 
 =head1 DESCRIPTION
 
+Conditions are part of Sieve's rules. Swiftsieve simplifies a condition to
+having a haystack, a needle and an operator.
+
+To get the text representation of this condition, ready for the Sieve server,
+you should call the write() method.
+
+=head1 METHODS
+
 =over
 
 =item B<new($source)>
@@ -62,7 +72,7 @@ sub new {
 
 Sets or returns the haystack.
 
-Possible haystacks are mail headers or size to match against the mail's size
+Possible haystacks are mail headers or size to match against the mail's size.
 
 =cut
 
@@ -105,8 +115,8 @@ sub _parse {
 
 Performs a sanity check on the condition.
 
-(This method is automatically called after parsing
-and before writing)
+(This method is automatically called after parsing and before writing)
+
 =cut
 sub validate {
     my($cond) = @_;
diff --git a/lib/App/Swiftsieve/Sieve/Rule.pm b/lib/App/Swiftsieve/Sieve/Rule.pm
index 0756013..c9f2230 100644
--- a/lib/App/Swiftsieve/Sieve/Rule.pm
+++ b/lib/App/Swiftsieve/Sieve/Rule.pm
@@ -31,13 +31,23 @@ App::Swiftsieve::Sieve::Rule - Handle a limited subset of Sieve
 
 =head1 SYNOPSIS
 
+    my $rule = new App::Swiftsieve::Sieve::Rule();
+
+    $rule->condition_join("anyof");
+    $rule->action_command("keep");
+    $rule->add_cond($condition);
+
+    print $rule->write();
+
+=head1 DESCRIPTION
+
 Rules are the workhorse of Sieve scripts. Swiftsieve limits rules to having
 multiple conditions, joined by allof or anyof, and a single action.
 
 To get the text representation of this rule, ready for the Sieve server, you
 should call the write() method.
 
-=head1 DESCRIPTION
+=head1 METHODS
 
 =over
 
@@ -89,13 +99,12 @@ sub _parse {
     return \%rule;
 }
 
-
 =item B<validate>
 
 Performs a sanity check on the rule, not including its conditions.
 
-(This method is automatically called after parsing
-and before writing)
+(This method is automatically called after parsing and before writing)
+
 =cut
 sub validate {
     my($rule) = @_;
@@ -136,7 +145,7 @@ sub requires {
 
 =item B<write>
 
-Returns the textual representation of this rule
+Returns the textual representation of this rule.
 
 =cut
 sub write {
@@ -168,7 +177,7 @@ sub write {
 
 =item B<conditions>
 
-Returns a list of Condition objects
+Returns a list of Condition objects.
 
 =cut
 sub conditions {
@@ -177,7 +186,7 @@ sub conditions {
 
 =item B<add_cond($cond)>
 
-Adds $cond to the rule's conditions
+Adds $cond to the rule's conditions.
 
 =cut
 sub add_cond {
diff --git a/lib/App/Swiftsieve/Sieve/Script.pm b/lib/App/Swiftsieve/Sieve/Script.pm
index f957aff..15b8986 100644
--- a/lib/App/Swiftsieve/Sieve/Script.pm
+++ b/lib/App/Swiftsieve/Sieve/Script.pm
@@ -30,20 +30,33 @@ App::Swiftsieve::Sieve::Script - Handle a limited subset of Sieve
 
 =head1 SYNOPSIS
 
+    my $source = <<EOF;
+    require ["fileinto"];
+
+    if anyof (header :matches "Subject" "TEST*")
+    {
+        fileinto "test";
+    }
+    EOF
+
+    my $script = new App::Swiftsieve::Sieve::Script($source);
+
+=head1 DESCRIPTION
+
 The Script class parses and writes the highest level of Sieve handling, the
 script.
 
 To get the text representation of this script, ready for the Sieve server, you
 should call the write() method.
 
-=head1 DESCRIPTION
+=head1 METHODS
 
 =over
 
 =item B<new($source)>
 
 Creates a new Script. If $source is defined, it will be parsed to create an
-object representation of the script
+object representation of the script.
 
 =cut
 sub new {
@@ -114,7 +127,7 @@ sub _parse {
 
 =item B<write>
 
-Returns the Sieve representation of this script
+Returns the Sieve representation of this script.
 
 =cut
 sub write {
@@ -135,7 +148,7 @@ sub write {
 
 =item B<rules>
 
-Returns a list of Rule objects
+Returns a list of Rule objects.
 
 =cut
 sub rules {
@@ -144,7 +157,7 @@ sub rules {
 
 =item B<add_rule($rule)>
 
-Adds $rule to the script
+Adds $rule to the script.
 
 =cut
 sub add_rule {
diff --git a/lib/App/Swiftsieve/Util.pm b/lib/App/Swiftsieve/Util.pm
index 8b152af..e786e10 100644
--- a/lib/App/Swiftsieve/Util.pm
+++ b/lib/App/Swiftsieve/Util.pm
@@ -26,10 +26,15 @@ use List::Util qw(first);
 
 
 =head1 NAME
+
 App::Swiftsieve::Util - Utility subroutines used in Swiftsieve
 
 =head1 DESCRIPTION
 
+These are just utility functions that happen to be used in Swiftsieve.
+
+=head1 FUNCTIONS
+
 =over
 
 =item B<allowed_value($value, $allowed)>
-- 
1.6.2