revised documentation for 5.0

[catagits/Catalyst-Runtime.git] / lib / Catalyst / Engine.pm

diff --git a/lib/Catalyst/Engine.pm b/lib/Catalyst/Engine.pm
index b7d525e..57e73ee 100644 (file)
--- a/lib/Catalyst/Engine.pm
+++ b/lib/Catalyst/Engine.pm
@@ -47,6 +47,9 @@ See L<Catalyst>.
 
 =head1 DESCRIPTION
 
+This is the core of catalyst. The various drivers are subclasses
+of this class.
+
 =head1 METHODS
 
 =over 4
@@ -71,6 +74,8 @@ sub benchmark {
 
 =item $c->comp($name)
 
+Shortcut for $c->component
+
 =item $c->component($name)
 
 Get a component object by name.
@@ -218,7 +223,8 @@ sub execute {
 
 =item $c->finalize
 
-Finalize request.
+Finalize request. This function can typically be overloaded with
+NEXT by plugins that need to do something at the end of the request.
 
 =cut
 
@@ -276,7 +282,8 @@ sub finalize_cookies {
 
 =item $c->finalize_error
 
-Finalize error.
+This is the default error screen displayed from finalize. Override
+with your own output if you need something special.
 
 =cut
 
@@ -379,7 +386,7 @@ sub finalize_error {
 
 =item $c->finalize_headers
 
-Finalize headers.
+Finalize headers. Null action by default.
 
 =cut
 
@@ -387,7 +394,7 @@ sub finalize_headers { }
 
 =item $c->finalize_output
 
-Finalize output.
+Finalize output. Null action by default
 
 =cut
 
@@ -399,6 +406,7 @@ Forward processing to a private action or a method from a class.
 If you define a class without method it will default to process().
 
     $c->forward('/foo');
+    $c->forward('/controller/action');
     $c->forward('index');
     $c->forward(qw/MyApp::Model::CDBI::Foo do_stuff/);
     $c->forward('MyApp::View::TT');
@@ -508,7 +516,7 @@ sub get_action {
 
 =item $c->handler( $class, $r )
 
-Handles the request.
+The main request handler.
 
 =cut
 
@@ -616,7 +624,7 @@ sub prepare {
 
 =item $c->prepare_action
 
-Prepare action.
+Prepare action for processing.
 
 =cut
 
@@ -661,7 +669,7 @@ sub prepare_action {
 
 =item $c->prepare_connection
 
-Prepare connection.
+Prepare connection. Null action by default
 
 =cut
 
@@ -669,7 +677,7 @@ sub prepare_connection { }
 
 =item $c->prepare_cookies
 
-Prepare cookies.
+Prepare cookies. 
 
 =cut
 
@@ -683,7 +691,7 @@ sub prepare_cookies {
 
 =item $c->prepare_headers
 
-Prepare headers.
+Prepare headers. Null action by default
 
 =cut
 
@@ -691,7 +699,7 @@ sub prepare_headers { }
 
 =item $c->prepare_parameters
 
-Prepare parameters.
+Prepare parameters. Null action by default
 
 =cut
 
@@ -699,7 +707,7 @@ sub prepare_parameters { }
 
 =item $c->prepare_path
 
-Prepare path and base.
+Prepare path and base. Null action by default
 
 =cut
 
@@ -707,7 +715,7 @@ sub prepare_path { }
 
 =item $c->prepare_request
 
-Prepare the engine request.
+Prepare the engine request. Null action by default
 
 =cut
 
@@ -715,7 +723,7 @@ sub prepare_request { }
 
 =item $c->prepare_uploads
 
-Prepare uploads.
+Prepare uploads.  Null action by default
 
 =cut
 
@@ -723,31 +731,36 @@ sub prepare_uploads { }
 
 =item $c->run
 
-Starts the engine.
+Starts the engine. Null action by default
 
 =cut
 
 sub run { }
 
-=item $c->request
-
 =item $c->req
 
-Returns a C<Catalyst::Request> object.
+Shortcut for $c->request
 
-    my $req = $c->req;
+=item $c->request
 
-=item $c->response
+Returns a C<Catalyst::Request> object.
+
+    my $req = $c->request;
 
 =item $c->res
 
+Shortcut for $c->response
+
+=item $c->response
+
 Returns a C<Catalyst::Response> object.
 
     my $res = $c->res;
 
 =item $c->set_action( $action, $code, $namespace, $attrs )
 
-Set an action in a given namespace.
+Set an action in a given namespace. Used to defined the actions
+in the attribute handlers.
 
 =cut
 
@@ -821,7 +834,7 @@ sub set_action {
 
 =item $class->setup
 
-Setup.
+Setup the application. required to initialize actions.
 
     MyApp->setup;
 
@@ -873,7 +886,7 @@ sub setup_actions {
 
 =item $class->setup_components
 
-Setup components.
+Setup all the components in YourApp::(M|V|C|Model|View|Controller)::*
 
 =cut
 
@@ -964,7 +977,8 @@ Contains the return value of the last executed action.
 
 =item $c->stash
 
-Returns a hashref containing all your data.
+The stash is a global hash which can be used to pass around data
+between your components.
 
     $c->stash->{foo} ||= 'yada';
     print $c->stash->{foo};
@@ -1001,9 +1015,22 @@ sub _class2prefix {
 
 =back
 
+=head1 SEE ALSO
+
+=over 4
+
+=item L<Catalyst::Engine::Apache> - Apache Engines for MP1/2
+=item L<Catalyst::Engine::CGI>    - CGI Engine
+=item L<Catalyst::Engine::FCGI>   - FastCGI Engine
+=item L<Catalyst::Engine::HTTP>   - Standalone Catalyst Server
+=item L<Catalyst::Engine::Test>   - Engine for testing
+
+=back
+
 =head1 AUTHOR
 
 Sebastian Riedel, C<sri@cpan.org>
+Marcus Ramberg, C<mramberg@cpan.org>
 
 =head1 COPYRIGHT