add some docs

1 files changed, 64 insertions, 0 deletions

diff --git a/lib/Plack/Middleware/Auth/Htpasswd.pm b/lib/Plack/Middleware/Auth/Htpasswd.pm
index 2f9d949..ff46005 100644
--- a/lib/Plack/Middleware/Auth/Htpasswd.pm
+++ b/lib/Plack/Middleware/Auth/Htpasswd.pm
@@ -9,6 +9,57 @@ use Authen::Htpasswd;
 use MIME::Base64;
 use Path::Class ();
 
+# ABSTRACT: http basic authentication through apache-style .htpasswd files
+
+=head1 SYNOPSIS
+
+  use Plack::Builder;
+  my $app = sub { ... };
+
+  builder {
+      enable "Auth::Htpasswd", file => '/path/to/.htpasswd';
+      $app;
+  };
+
+or
+
+  builder {
+      enable "Auth::Htpasswd", file_root => '/path/to/my/static/files';
+      $app;
+  };
+  
+=head1 DESCRIPTION
+
+This middleware enables HTTP Basic authenication, based on the users in an
+L<Apache-style htpasswd file|http://httpd.apache.org/docs/2.0/programs/htpasswd.html>.
+You can either specify the file directly, through the C<file> option, or use
+the C<file_root> option to specify the root directory on the filesystem that
+corresponds to the web application root. This second option is more useful when
+using an app that is closely tied to the filesystem, such as
+L<Plack::App::Directory>. If C<file_root> is used, the requested path will be
+inspected, and a file named C<.htpasswd> will be checked in each containing
+directory, up to the C<file_root>. The first one found will be used to validate
+the requested user.
+
+=head1 CONFIGURATION
+
+=head2 file
+
+Name of a .htpasswd file to read authentication information from. Required if
+C<file_root> is not set.
+
+=head2 file_root
+
+Path to the on-disk directory that corresponds to the root URL path of the app.
+Required C<file> is not set, and ignored if C<file> is set.
+
+=head2 realm
+
+Realm name to display in the basic authentication dialog. Defaults to
+'restricted area'.
+
+=cut
+
 sub prepare_app {
     my $self = shift;
     die "must specify either file or file_root"
@@ -81,4 +132,17 @@ sub unauthorized {
     ];
 }
 
+=head1 SEE ALSO
+
+L<Plack>
+
+L<Plack::Middleware::Auth::Basic>
+
+=head1 CREDITS
+
+Large parts of this code were modeled after (read: stolen from)
+L<Plack::Middleware::Auth::Basic> by Tatsuhiko Miyagawa.
+
+=cut
+
 1;