From 341e823680b75f504c90bd43c7e7a9eea2c3db2b Mon Sep 17 00:00:00 2001
From: Ian Jackson <ijackson@chiark.greenend.org.uk>
Date: Tue, 19 Mar 2013 01:09:59 +0000
Subject: [PATCH] docs: more work

---
 caf.pod | 50 +++++++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 47 insertions(+), 3 deletions(-)

diff --git a/caf.pod b/caf.pod
index 673aeee..5dd2f07 100644
--- a/caf.pod
+++ b/caf.pod
@@ -268,7 +268,7 @@ C</usr/local>.  See C<srcdump_system_dir>.
 
 For each source item in a dvcs, the entire dvcs history does
 not contain anything confidential (or libellous).  Also, all files which
-contain secrets are in the dvcs's C<.ignore> file.  See
+contain secrets are in the dvcs's I<.ignore> file.  See
 C<srcdump_vcsscript_git> et al.
 
 =item *
@@ -304,13 +304,13 @@ See L</SETTINGS> below.
 
 =item C<< $verifier->new_request($cgi_query) >>
 
-Prepares to process a request.  C<$cgi_query> should normally
+Prepares to process a request.  I<$cgi_query> should normally
 be the query object from L<CGI(3perl)>.  Most of the default
 hook methods assume that it is; however if you replace enough of
 the hook methods then you can pass any value you like and it
 will be passed to your hooks.
 
-The return value is the authentication request object (C<$authreq>)
+The return value is the authentication request object (I<$authreq>)
 which is used to check the incoming request and will contain
 information about its credentials.
 
@@ -337,3 +337,47 @@ the application should not process the request further.
 Discards the resources (open files, etc.) in the verifier object.
 
 =back
+
+=head REQUEST-HANDLING FUNCTIONS AND METHODS
+
+All of these are only valid after C<check_divert> or C<check_ok> has
+been called.  (In the case of C<check_ok> it won't normally be sensible
+to call these functions unless C<check_ok> returned true.)
+
+=item C<< $authreq->get_divert() >>
+
+Returns the value previously returned by C<check_divert>.
+
+=item C<< $authreq->get_username() >>
+
+Returns the name of the logged-in user.  If the user was not logged
+in (or their session had timed out, or something), returns undef.
+
+=head RESPONSE-RELATED FUNCTIONS AND METHODS
+
+=item C<< $authreq->url_with_query_params($params, [$nonpagetype]) >>
+
+Convenience function which returns a url for a GET request to this
+application.
+
+I<$params> is a hashref specifying the parameters and the PATH_INFO.
+The keys are the parameter names, and the values are array refs with
+the parameter value(s) (as strings, as yet unquoted).  (They are array
+refs because it is possible to pass multiple values for the same
+parameter in a single request; normally each arrayref would be a
+singleton.)
+
+The request path will be the path to the application.  If a parameter
+with name C<< '' >> is supplied, it is taken as the PATH_INFO to
+supply - its value will be appended to the application path.  (It
+should normally start with C<< / >>, and only one value should be
+supplied.)
+
+=item C<< $authreq->chain_params() >>
+
+Returns a hash of the "relevant" parameters to this request, in a form
+used by XXX.  This is all of the query parameters which are not
+related to CGI::Auth::Flexible.  The PATH_INFO from the request is
+returned as the parameter C<< '' >>.
+
+=back
-- 
2.30.2