From: Marcus Ramberg <marcus@nordaaker.com>
Date: Sat, 19 Mar 2005 18:10:04 +0000 (+0000)
Subject: doc patch from Andrew Ford
X-Git-Tag: 5.7099_04~1759
X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?p=catagits%2FCatalyst-Runtime.git;a=commitdiff_plain;h=23f9d93414eadb11350029f13b51841d8309363b;hp=502619e59524272fc07491f9d2d6958304df3fa4

doc patch from Andrew Ford
---

diff --git a/Changes b/Changes
index d680e75..db862ae 100644
--- a/Changes
+++ b/Changes
@@ -2,9 +2,11 @@ This file documents the revision history for Perl extension Catalyst.
 
 4.28  XXX XXX XX XX:00:00 2005
         - fixed isa tree (Christian Hansen)
+        - Reworked documentation (Andrew Ford <A.Ford@ford-mason.co.uk>)
 
 4.27  Sat Mar 19 01:00:00 2005
         - debug message for parameters
+        - Fix redirects (Christian Hansen <ch@ngmedia.com>)
         - some random fixes
         - new helper api for Catalyst::Helper::* support
           you have to update script/create.pl to use it
diff --git a/lib/Catalyst.pm b/lib/Catalyst.pm
index d238867..d205183 100644
--- a/lib/Catalyst.pm
+++ b/lib/Catalyst.pm
@@ -69,37 +69,49 @@ The key concept of Catalyst is DRY (Don't Repeat Yourself).
 
 See L<Catalyst::Manual> for more documentation.
 
-Omit the Catalyst::Plugin:: prefix from plugins.
-So Catalyst::Plugin::My::Module becomes My::Module.
+Catalyst plugins can be loaded by naming them as arguments to the "use Catalyst" statement.
+Omit the C<Catalyst::Plugin::> prefix from the plugin name, 
+so C<Catalyst::Plugin::My::Module> becomes C<My::Module>.
 
     use Catalyst 'My::Module';
 
-You can also set special flags like -Debug and -Engine.
+Special flags like -Debug and -Engine can also be specifed as arguments when
+Catalyst is loaded:
 
     use Catalyst qw/-Debug My::Module/;
 
-The position of plugins and flags in the chain is important,
-because they are loaded in the same order they appear.
+The position of plugins and flags in the chain is important, because they are
+loaded in exactly the order that they appear.
 
-=head2 -Debug
+The following flags are supported:
+
+=over 4
+
+=item -Debug
+
+enables debug output, i.e.:
 
     use Catalyst '-Debug';
 
-is equivalent to
+this is equivalent to:
 
     use Catalyst;
     sub debug { 1 }
 
-=head2 -Engine
+=item -Engine
 
 Force Catalyst to use a specific engine.
-Omit the Catalyst::Engine:: prefix.
+Omit the C<Catalyst::Engine::> prefix of the engine name, i.e.:
 
     use Catalyst '-Engine=CGI';
 
-=head2 METHODS
+=back
 
-=head3 debug
+=head1 METHODS
+
+=over 4
+
+=item debug
 
 Overload to enable debug messages.
 
@@ -107,7 +119,7 @@ Overload to enable debug messages.
 
 sub debug { 0 }
 
-=head3 config
+=item config
 
 Returns a hashref containing your applications settings.
 
@@ -179,6 +191,8 @@ sub import {
     $caller->log->debug(qq/Loaded engine "$engine"/) if $caller->debug;
 }
 
+=back
+
 =head1 SUPPORT
 
 IRC:
diff --git a/lib/Catalyst/Base.pm b/lib/Catalyst/Base.pm
index f0138cf..6448f3d 100644
--- a/lib/Catalyst/Base.pm
+++ b/lib/Catalyst/Base.pm
@@ -48,9 +48,12 @@ This is the universal base class for Catalyst components
 It provides you with a generic new() for instantiation through Catalyst's
 component loader with config() support and a process() method placeholder.
 
-=head2 METHODS
+=head1 METHODS
+
+=over 4
+
+=item new($c)
 
-=head3 new
 =cut
 
 sub new {
@@ -58,7 +61,14 @@ sub new {
     return $self->NEXT::new( $self->config );
 }
 
-=head3 config
+# remember to leave blank lines between the consecutive =item's
+# otherwise the pod tools don't recognize the subsequent =items
+
+=item $c->config
+
+=item $c->config($hashref)
+
+=item $c->config($key, $value, ...)
 
 =cut
 
@@ -74,7 +84,7 @@ sub config {
     return $self->_config;
 }
 
-=head3 process
+=item $c->process()
 
 =cut
 
diff --git a/lib/Catalyst/Engine.pm b/lib/Catalyst/Engine.pm
index ce8e940..260c9e3 100644
--- a/lib/Catalyst/Engine.pm
+++ b/lib/Catalyst/Engine.pm
@@ -37,9 +37,15 @@ See L<Catalyst>.
 
 =head1 DESCRIPTION
 
-=head2 METHODS
+=head1 METHODS
 
-=head3 action
+=over 4
+
+=item $c->action( $name => $coderef, ... )
+
+=item $c->action( $name )
+
+=item $c->action
 
 Add one or more actions.
 
@@ -118,7 +124,8 @@ sub action {
     }
 }
 
-=head3 benchmark
+
+=item $c->benchmark($coderef)
 
 Takes a coderef with arguments and returns elapsed time as float.
 
@@ -136,7 +143,9 @@ sub benchmark {
     return wantarray ? ( $elapsed, @return ) : $elapsed;
 }
 
-=head3 component (comp)
+=item $c->comp($name)
+
+=item $c->component($name)
 
 Get a component object by name.
 
@@ -160,7 +169,11 @@ sub component {
     }
 }
 
-=head3 errors
+=item $c->errors
+
+=item $c->errors($error, ...)
+
+=item $c->errors($arrayref)
 
 Returns an arrayref containing errors messages.
 
@@ -179,7 +192,7 @@ sub errors {
     return $c->{errors};
 }
 
-=head3 finalize
+=item $c->finalize
 
 Finalize request.
 
@@ -187,6 +200,13 @@ Finalize request.
 
 sub finalize {
     my $c = shift;
+
+    if ( my $location = $c->res->redirect ) {
+        $c->log->debug(qq/Redirecting to "$location"/) if $c->debug;
+        $c->res->headers->header( Location => $location );
+        $c->res->status(302);
+    }
+
     if ( !$c->res->output || $#{ $c->errors } >= 0 ) {
         $c->res->headers->content_type('text/html');
         my $name = $c->config->{name} || 'Catalyst Application';
@@ -280,18 +300,13 @@ sub finalize {
 </html>
 
     }
-    if ( my $location = $c->res->redirect ) {
-        $c->log->debug(qq/Redirecting to "$location"/) if $c->debug;
-        $c->res->headers->header( Location => $location );
-        $c->res->status(302);
-    }
     $c->res->headers->content_length( length $c->res->output );
     my $status = $c->finalize_headers;
     $c->finalize_output;
     return $status;
 }
 
-=head3 finalize_headers
+=item $c->finalize_headers
 
 Finalize headers.
 
@@ -299,7 +314,7 @@ Finalize headers.
 
 sub finalize_headers { }
 
-=head3 finalize_output
+=item $c->finalize_output
 
 Finalize output.
 
@@ -307,7 +322,7 @@ Finalize output.
 
 sub finalize_output { }
 
-=head3 forward
+=item $c->forward($command)
 
 Forward processing to a private/public action or a method from a class.
 If you define a class without method it will default to process().
@@ -373,7 +388,7 @@ sub forward {
     return $c->process( $class, $code );
 }
 
-=head3 handler
+=item $c->handler($r)
 
 Handles the request.
 
@@ -440,9 +455,9 @@ sub handler {
     return $status;
 }
 
-=head3 prepare
+=item $c->prepare($r)
 
-Turns the request (Apache, CGI...) into a Catalyst context.
+Turns the engine-specific request (Apache, CGI...) into a Catalyst context.
 
 =cut
 
@@ -494,7 +509,7 @@ sub prepare {
     return $c;
 }
 
-=head3 prepare_action
+=item $c->prepare_action
 
 Prepare action.
 
@@ -547,7 +562,7 @@ sub prepare_action {
       if ( $c->debug && @args );
 }
 
-=head3 prepare_cookies;
+=item $c->prepare_cookies;
 
 Prepare cookies.
 
@@ -555,7 +570,7 @@ Prepare cookies.
 
 sub prepare_cookies { }
 
-=head3 prepare_headers
+=item $c->prepare_headers
 
 Prepare headers.
 
@@ -563,7 +578,7 @@ Prepare headers.
 
 sub prepare_headers { }
 
-=head3 prepare_parameters
+=item $c->prepare_parameters
 
 Prepare parameters.
 
@@ -571,7 +586,7 @@ Prepare parameters.
 
 sub prepare_parameters { }
 
-=head3 prepare_path
+=item $c->prepare_path
 
 Prepare path and base.
 
@@ -579,7 +594,7 @@ Prepare path and base.
 
 sub prepare_path { }
 
-=head3 prepare_request
+=item $c->prepare_request
 
 Prepare the engine request.
 
@@ -587,7 +602,7 @@ Prepare the engine request.
 
 sub prepare_request { }
 
-=head3 prepare_uploads
+=item $c->prepare_uploads
 
 Prepare uploads.
 
@@ -595,7 +610,7 @@ Prepare uploads.
 
 sub prepare_uploads { }
 
-=head3 process
+=item $c->process($class, $coderef)
 
 Process a coderef in given class and catch exceptions.
 Errors are available via $c->errors.
@@ -627,7 +642,7 @@ sub process {
     return $status;
 }
 
-=head3 remove_action
+=item $c->remove_action($action)
 
 Remove an action.
 
@@ -650,19 +665,23 @@ sub remove_action {
     }
 }
 
-=head3 request (req)
+=item $c->request
+
+=item $c->req
 
 Returns a C<Catalyst::Request> object.
 
     my $req = $c->req;
 
-=head3 response (res)
+=item $c->response
+
+=item $c->res
 
 Returns a C<Catalyst::Response> object.
 
     my $res = $c->res;
 
-=head3 setup
+=item $class->setup
 
 Setup.
 
@@ -679,7 +698,7 @@ sub setup {
     }
 }
 
-=head3 setup_components
+=item $class->setup_components
 
 Setup components.
 
@@ -715,7 +734,7 @@ sub setup_components {
       if $self->debug;
 }
 
-=head3 stash
+=item $c->stash
 
 Returns a hashref containing all your data.
 
@@ -750,6 +769,8 @@ sub _class2prefix {
     return $prefix;
 }
 
+=back
+
 =head1 AUTHOR
 
 Sebastian Riedel, C<sri@cpan.org>
diff --git a/lib/Catalyst/Engine/Apache.pm b/lib/Catalyst/Engine/Apache.pm
index fc69b1c..55d8e89 100644
--- a/lib/Catalyst/Engine/Apache.pm
+++ b/lib/Catalyst/Engine/Apache.pm
@@ -35,23 +35,29 @@ See L<Catalyst>.
 
 =head1 DESCRIPTION
 
-The Apache Engine.
+This is the Catalyst engine specialized for Apache (i.e. for mod_perl).
 
-=head2 METHODS
+=head1 METHODS
 
-=head3 apache_request
+=over 4
+
+=item $c->apache_request
 
 Returns an C<Apache::Request> object.
 
-=head3 original_request
+=item $c->original_request
 
 Returns the original Apache request object.
 
-=head2 OVERLOADED METHODS
+=back
+
+=head1 OVERLOADED METHODS
 
 This class overloads some methods from C<Catalyst::Engine>.
 
-=head3 finalize_headers
+=over 4
+
+=item $c->finalize_headers
 
 =cut
 
@@ -81,7 +87,7 @@ sub finalize_headers {
     return 0;
 }
 
-=head3 finalize_output
+=item $c->finalize_output
 
 =cut
 
@@ -90,7 +96,7 @@ sub finalize_output {
     $c->original_request->print( $c->response->{output} );
 }
 
-=head3 prepare_cookies
+=item $c->prepare_cookies
 
 =cut
 
@@ -102,7 +108,7 @@ sub prepare_cookies {
         { Apache::Cookie->new( $c->apache_request )->fetch } );
 }
 
-=head3 prepare_headers
+=item $c->prepare_headers
 
 =cut
 
@@ -112,7 +118,7 @@ sub prepare_headers {
     $c->req->headers->header( %{ $c->apache_request->headers_in } );
 }
 
-=head3 prepare_parameters
+=item $c->prepare_parameters
 
 =cut
 
@@ -126,7 +132,7 @@ sub prepare_parameters {
     $c->req->parameters( \%args );
 }
 
-=head3 prepare_path
+=item $c->prepare_path
 
 =cut
 
@@ -145,7 +151,7 @@ sub prepare_path {
     $c->req->base( $base->as_string );
 }
 
-=head3 prepare_request
+=item $c->prepare_request($r)
 
 =cut
 
@@ -155,7 +161,7 @@ sub prepare_request {
     $c->original_request($r);
 }
 
-=head3 prepare_uploads
+=item $c->prepare_uploads
 
 =cut
 
@@ -171,6 +177,8 @@ sub prepare_uploads {
     }
 }
 
+=back
+
 =head1 SEE ALSO
 
 L<Catalyst>.
diff --git a/lib/Catalyst/Engine/CGI.pm b/lib/Catalyst/Engine/CGI.pm
index e682f6e..1efa954 100644
--- a/lib/Catalyst/Engine/CGI.pm
+++ b/lib/Catalyst/Engine/CGI.pm
@@ -18,6 +18,8 @@ Catalyst::Engine::CGI - The CGI Engine
 
 =head1 SYNOPSIS
 
+A script using the Catalyst::Engine::CGI module might look like:
+
     #!/usr/bin/perl -w
 
     use strict;
@@ -26,34 +28,48 @@ Catalyst::Engine::CGI - The CGI Engine
 
     MyApp->run;
 
-See L<Catalyst>.
+The application module (C<MyApp>) would use C<Catalyst>, which loads the
+appropriate engine module.
 
 =head1 DESCRIPTION
 
-This is the CGI engine for Catalyst.
+This is the Catalyst engine specialized for the CGI environment (using the
+C<CGI::Simple> and C<CGI::Cookie> modules).  Normally Catalyst will select the
+appropriate engine according to the environment that it detects, however you
+can force Catalyst to use the CGI engine by specifying the following in your
+application module:
+
+    use Catalyst qw(-Engine=CGI);
 
-The script shown above must be designated as a "Non-parsed Headers"
-script to function properly.
-To do this in Apache name the script starting with C<nph->.
+Catalyst::Engine::CGI generates a full set of HTTP headers, which means that
+applications using the engine must be be configured as "Non-parsed Headers"
+scripts (at least when running under Apache).  To configure this under Apache
+name the starting with C<nph->.
 
 The performance of this way of using Catalyst is not expected to be
 useful in production applications, but it may be helpful for development.
 
-=head2 METHODS
+=head1 METHODS
 
-=head3 run
+=over 4
+
+=item $c->run
 
 To be called from a CGI script to start the Catalyst application.
 
-=head3 cgi
+=item $c->cgi
 
 This config parameter contains the C<CGI::Simple> object.
 
-=head2 OVERLOADED METHODS
+=back
+
+=head1 OVERLOADED METHODS
 
 This class overloads some methods from C<Catalyst>.
 
-=head3 finalize_headers
+=over 4
+
+=item $c->finalize_headers
 
 =cut
 
@@ -79,7 +95,9 @@ sub finalize_headers {
     print $c->cgi->header(%headers);
 }
 
-=head3 finalize_output
+=item $c->finalize_output
+
+Prints the response output to STDOUT.
 
 =cut
 
@@ -88,13 +106,15 @@ sub finalize_output {
     print $c->response->output;
 }
 
-=head3 prepare_cookies
+=item $c->prepare_cookies
+
+Sets up cookies.
 
 =cut
 
 sub prepare_cookies { shift->req->cookies( { CGI::Cookie->fetch } ) }
 
-=head3 prepare_headers
+=item $c->prepare_headers
 
 =cut
 
@@ -107,7 +127,7 @@ sub prepare_headers {
     }
 }
 
-=head3 prepare_parameters
+=item $c->prepare_parameters
 
 =cut
 
@@ -121,7 +141,7 @@ sub prepare_parameters {
     $c->req->parameters( {%vars} );
 }
 
-=head3 prepare_path
+=item $c->prepare_path
 
 =cut
 
@@ -142,13 +162,13 @@ sub prepare_path {
     $c->req->base( $base->as_string );
 }
 
-=head3 prepare_request
+=item $c->prepare_request
 
 =cut
 
 sub prepare_request { shift->cgi( CGI::Simple->new ) }
 
-=head3 prepare_uploads
+=item $c->prepare_uploads
 
 =cut
 
@@ -165,6 +185,8 @@ sub prepare_uploads {
 
 sub run { shift->handler }
 
+=back
+
 =head1 SEE ALSO
 
 L<Catalyst>.