From: Stevan Little <stevan.little@iinteractive.com>
Date: Sat, 12 Dec 2009 16:55:24 +0000 (-0500)
Subject: docs, docs and more docs
X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?p=catagits%2FWeb-Session.git;a=commitdiff_plain;h=43f34c01a20c9f5b05bd43532d4b564fe6bd4817

docs, docs and more docs
---

diff --git a/lib/Plack/Session.pm b/lib/Plack/Session.pm
index 223cf37..6473b27 100644
--- a/lib/Plack/Session.pm
+++ b/lib/Plack/Session.pm
@@ -68,14 +68,31 @@ Plack::Session - Middleware for session management
 
 =item B<new ( %params )>
 
+The constructor expects keys in C<%params> for I<state>,
+I<store> and I<request>. The I<request> param is expected to be
+a L<Plack::Request> instance or an object with an equivalent
+interface.
+
 =item B<id>
 
+This is the accessor for the session id.
+
 =item B<state>
 
+This is expected to be a L<Plack::Session::State> instance or
+an object with an equivalent interface.
+
 =item B<store>
 
+This is expected to be a L<Plack::Session::Store> instance or
+an object with an equivalent interface.
+
 =back
 
+=head2 Session Data Storage
+
+These methods delegate to appropriate methods on the C<store>.
+
 =over 4
 
 =item B<get ( $key )>
@@ -86,12 +103,25 @@ Plack::Session - Middleware for session management
 
 =back
 
+=head2 Session Lifecycle Management
+
 =over 4
 
 =item B<expire>
 
+This method can be called to expire the current session id. It
+will call the C<cleanup> method on the C<store> and the C<finalize>
+method on the C<state>, passing both of them the session id and
+the C<$response>.
+
 =item B<finalize ( $response )>
 
+This method should be called at the end of the response cycle. It
+will call the C<persist> method on the C<store> and the
+C<expire_session_id> method on the C<state>, passing both of them
+the session id. The C<$response> is expected to be a L<Plack::Response>
+instance or an object with an equivalent interface.
+
 =back
 
 =head1 BUGS
diff --git a/lib/Plack/Session/State.pm b/lib/Plack/Session/State.pm
index f55d9d7..9b8314f 100644
--- a/lib/Plack/Session/State.pm
+++ b/lib/Plack/Session/State.pm
@@ -79,28 +79,69 @@ Plack::Session::State - Basic parameter-based session state
 
 =item B<session_key>
 
+This is the name of the session key, it default to 'plack_session'.
+
 =item B<sid_generator>
 
+This is a CODE ref used to generate unique session ids.
+
 =back
 
+=head2 Session ID Managment
+
 =over 4
 
 =item B<get_session_id ( $request )>
 
+Given a C<$request> this will first attempt to extract the session,
+if the is expired or does not exist, it will then generate a new
+session. The C<$request> is expected to be a L<Plack::Request> instance
+or an object with an equivalent interface.
+
 =item B<extract ( $request )>
 
+This will attempt to extract the session from a C<$request> by looking
+for the C<session_key> in the C<$request> params. It will then check to
+see if the session has expired and return the session id if it is not.
+The C<$request> is expected to be a L<Plack::Request> instance or an
+object with an equivalent interface.
+
 =item B<generate ( $request )>
 
+This will generate a new session id using the C<sid_generator> callback.
+The C<$request> argument is not used by this method but is there for
+use by subclasses. The C<$request> is expected to be a L<Plack::Request>
+instance or an object with an equivalent interface.
+
 =item B<finalize ( $session_id, $response )>
 
+Given a C<$session_id> and a C<$response> this will perform any
+finalization nessecary to preserve state. This method is called by
+the L<Plack::Session> C<finalize> method. The C<$response> is expected
+to be a L<Plack::Response> instance or an object with an equivalent
+interface.
+
 =back
 
+=head2 Session Expiration Handling
+
 =over 4
 
 =item B<expire_session_id ( $id )>
 
+This will mark the session for C<$id> as expired. This method is called
+by the L<Plack::Session> C<expire> method.
+
+=item B<is_session_expired ( $id )>
+
+This will check to see if the session C<$id> has been marked as
+expired.
+
 =item B<check_expired ( $id )>
 
+Given an session C<$id> this will return C<undef> if the session is
+expired or return the C<$id> if it is not.
+
 =back
 
 =head1 BUGS
diff --git a/lib/Plack/Session/State/Cookie.pm b/lib/Plack/Session/State/Cookie.pm
index 6bd11c3..6440ebd 100644
--- a/lib/Plack/Session/State/Cookie.pm
+++ b/lib/Plack/Session/State/Cookie.pm
@@ -53,6 +53,9 @@ Plack::Session::State::Cookie - Basic cookie-based session state
 
 =head1 DESCRIPTION
 
+This is a subclass of L<Plack::Session::State> and implements it's
+full interface.
+
 =head1 METHODS
 
 =over 4
@@ -69,20 +72,6 @@ Plack::Session::State::Cookie - Basic cookie-based session state
 
 =back
 
-=over 4
-
-=item B<extract ( $request )>
-
-=item B<finalize ( $session_id, $response )>
-
-=back
-
-=over 4
-
-=item B<expire_session_id ( $id )>
-
-=back
-
 =head1 BUGS
 
 All complex software has bugs lurking in it, and this module is no
diff --git a/lib/Plack/Session/Store.pm b/lib/Plack/Session/Store.pm
index e20c196..b742d0d 100644
--- a/lib/Plack/Session/Store.pm
+++ b/lib/Plack/Session/Store.pm
@@ -55,6 +55,8 @@ Plack::Session::Store - Basic in-memory session store
 
 =back
 
+=head2 Session Data Management
+
 =over 4
 
 =item B<fetch ( $session_id, $key )>
@@ -65,12 +67,22 @@ Plack::Session::Store - Basic in-memory session store
 
 =back
 
+=head2 Storage Management
+
 =over 4
 
 =item B<persist ( $session_id, $response )>
 
+This method will perform any data persistence nessecary to maintain
+data across requests. This method is called by the L<Plack::Session>
+C<finalize> method. The C<$response> is expected to be a L<Plack::Response>
+instance or an object with an equivalent interface.
+
 =item B<cleanup ( $session_id )>
 
+This method is called by the L<Plack::Session> C<expire> method and
+is used to remove any session data.
+
 =back
 
 =head1 BUGS
diff --git a/lib/Plack/Session/Store/CHI.pm b/lib/Plack/Session/Store/CHI.pm
index 91579ef..6a155ec 100644
--- a/lib/Plack/Session/Store/CHI.pm
+++ b/lib/Plack/Session/Store/CHI.pm
@@ -53,6 +53,8 @@ sub cleanup {
 
 __END__
 
+=pod
+
 =head1 NAME
 
 Plack::Session::Store::CHI - CHI session store
@@ -68,33 +70,37 @@ Plack::Session::Store::CHI - CHI session store
   };
 
   builder {
-      enable 'Session', store => Plack::Session::Store::CHI->new(chi => CHI->new(driver => 'FastMmap'));
+      enable 'Session',
+          store => Plack::Session::Store::CHI->new(
+              chi => CHI->new(driver => 'FastMmap')
+          );
       $app;
   };
 
-=head1 METHODS
-
-=over 4
+=head1 DESCRIPTION
 
-=item B<new ( %params )>
+This is a subclass of L<Plack::Session::Store> and implements
+it's full interface.
 
-=back
+=head1 METHODS
 
 =over 4
 
-=item B<fetch ( $session_id, $key )>
+=item B<new ( %params )>
 
-=item B<store ( $session_id, $key, $data )>
+The constructor expects an the I<chi> param to be an
+instance of L<CHI::Driver>, it will throw an exception
+if that is not the case.
 
-=item B<delete ( $session_id, $key )>
+=item B<chi>
 
 =back
 
-=over 4
+=head1 BUGS
 
-=item B<cleanup ( $session_id )>
-
-=back
+All complex software has bugs lurking in it, and this module is no
+exception. If you find a bug please either email me, or add the bug
+to cpan-RT.
 
 =head1 AUTHOR