# HG changeset patch
# User Heiko Schlittermann <hs@schlittermann.de>
# Date 1464891153 -7200
# Node ID da29842506b417de7c59d1bdc7f16ffdb3cb3c77
# Parent  16b4815a6a1500f8fe6b047106681d9a523fe3e0
Add POD documentation to the Exim::Grey.pm

diff -r 16b4815a6a15 -r da29842506b4 lib/Exim/Grey.pm
--- a/lib/Exim/Grey.pm	Wed Jun 01 11:18:48 2016 +0200
+++ b/lib/Exim/Grey.pm	Thu Jun 02 20:12:33 2016 +0200
@@ -1,4 +1,5 @@
 package Exim::Grey;
+# for usage please see at the end
 
 use strict;
 use warnings;
@@ -20,7 +21,7 @@
 
 my %DEFAULT = (
     delay => 600,
-    db    => "seen",
+    db    => 'seen',
 );
 
 sub unseen;
@@ -31,24 +32,7 @@
 sub connectDB($$);
 sub getDefault() { %DEFAULT }
 
-# Usage:
-# 	${perl{unseen}{KEY}}
-# 	${perl{unseen}{KEY}{600}}
-# 	${perl{unseen}{KEY}{600}{seen}}
-# 	${perl{unseen}{KEY}{600}{$spool_directory/grey/seen}}
-#
-# With KEY being something to identify the second delivery attempt
-# I recommend using <$sender_address>:<$local_part@$domain>
-#
-# If KEY has a /... suffix, this suffix is used for auto-whitelisting.
-# I recommend using $sender_host_address.
-#
-# defer  condition = ${perl{unseen}{<$sender_address>:<$local_part@$domain>/$sender_host_address}}
-#
-# record structure: key:   item\0
-#                   value: timestamp(creation) timestamp(usage)[ auto]\0
-# (This way we're compatible with ${lookup{...}dbm{...}})
-#
+
 # dbm file is relativ to $spool_directory/grey, EXCEPT its name
 # starts with "./" or "/".
 
@@ -203,4 +187,62 @@
 
 1;
 
+__END__
+=head1 NAME
+
+ Exim::Grey
+
+=head1 SYNOPSIS
+
+ perl_startup use Exim::Grey qw(unseen);
+ ...
+ acl rcpt
+    defer condition = ${perl{unseen}{<$sender_address>:<$local_part@$domain>}}
+
+=head1 DESCRIPTION
+
+This is a module to be loade by Exim, the MTA. On request it exports
+a single function C<unseen()>. This function may be used in the ACL section
+to support greylisting.
+
+=head1 FUNCTIONS
+
+=over
+
+=item scalar B<unseen>(I<key>, I<delay>, I<db>)
+
+This function returns I<true> if the key is already known in the I<db> database
+for the minimum I<delay> time. (Note: The database may be cleaned regularly by
+the compangion L<exigrey> tool.)
+
+The I<key> is mandotory, the default I<delay> is 600 seconds and the default I<db>
+is called F<seen>.
+
+I<Key> may contain a suffix, separated with '/'. This suffix is used for
+automatic whitelisting.
+
+=back
+
+=head1 INTERNALS
+
+=head2 Format of the database
+
+The record structure is
+
+ key:   item\0
+ value: timestamp(creation) timestamp(usage) counter[ flags]\0
+
+This way we are compatible with ${lookup{...}dbm{...}}
+
+=head1 FILES
+
+The database files are placed in C<$spool_directory/grey/>.
+
+=head1 SEE ALSO
+
+The companion tool L<exigrey> should be used for inspection and manipulation
+of the database.
+
+=cut
+
 # vim:aw et sw=4 ts=4: