From: Marcus Ramberg <marcus@nordaaker.com>
Date: Wed, 15 Mar 2006 22:50:02 +0000 (+0000)
Subject: added docs for engine/dispatcher
X-Git-Tag: 5.7099_04~672
X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?p=catagits%2FCatalyst-Runtime.git;a=commitdiff_plain;h=4ab87e274ac0a05f98c10a4cdba467ba4398b0d3

added docs for engine/dispatcher
---

diff --git a/lib/Catalyst/Action.pm b/lib/Catalyst/Action.pm
index 8e5ea75..ca695c4 100644
--- a/lib/Catalyst/Action.pm
+++ b/lib/Catalyst/Action.pm
@@ -28,15 +28,27 @@ See L<Catalyst>.
 
 =head1 DESCRIPTION
 
+This class represents a Catalyst Action. You can access the object for the 
+currently dispatched action via $c->action
+
 =head1 METHODS
 
 =head2 attributes
 
+The sub attributes that are set for this action, like Local, Path, Private
+and so on.
+
 =head2 class
 
+Returns the class name of this action
+
 =head2 code
 
-=head2 execute
+Returns a code reference to this action
+
+=head2 execute <c>
+
+Execute this action against a context
 
 =cut
 
@@ -46,7 +58,9 @@ sub execute {    # Execute ourselves against a context
     return $c->execute( $self->class, $self );
 }
 
-=head2 match
+=head2 match <context>
+
+Check Args setting, and makes sure number of args matches the setting.
 
 =cut
 
@@ -58,10 +72,16 @@ sub match {
 
 =head2 namespace
 
+Returns the private namespace this action lives in.
+
 =head2 reverse
 
+Returns the private path for this action.
+
 =head2 name
 
+returns the sub name of this action.
+
 =head1 AUTHOR
 
 Matt S. Trout
diff --git a/lib/Catalyst/DispatchType.pm b/lib/Catalyst/DispatchType.pm
index 98ac0eb..196d3fd 100644
--- a/lib/Catalyst/DispatchType.pm
+++ b/lib/Catalyst/DispatchType.pm
@@ -17,18 +17,29 @@ See L<Catalyst>.
 
 =head2 $self->list($c)
 
+abstract method, to be implemented by dispatchtypes. Called to display
+info in debug log.
+
 =cut
 
 sub list { }
 
 =head2 $self->match( $c, $path )
 
+abstract method, to be implemented by dispatchtypes. Returns true if the
+dispatch type matches the given path
+
 =cut
 
 sub match { die "Abstract method!" }
 
 =head2 $self->register( $c, $action )
 
+abstract method, to be implemented by dispatchtypes. Takes a
+context object and a L<Catalyst::Action> object. 
+
+Should return true if it registers something, or false otherwise.
+
 =cut
 
 sub register { }
diff --git a/lib/Catalyst/DispatchType/Default.pm b/lib/Catalyst/DispatchType/Default.pm
index abe887e..58779fa 100644
--- a/lib/Catalyst/DispatchType/Default.pm
+++ b/lib/Catalyst/DispatchType/Default.pm
@@ -17,6 +17,9 @@ See L<Catalyst>.
 
 =head2 $self->match( $c, $path )
 
+Check if default action matches, and set action if it does. 
+Will be called last for each controller.
+
 =cut
 
 sub match {
diff --git a/lib/Catalyst/DispatchType/Index.pm b/lib/Catalyst/DispatchType/Index.pm
index f876850..58420e3 100644
--- a/lib/Catalyst/DispatchType/Index.pm
+++ b/lib/Catalyst/DispatchType/Index.pm
@@ -17,6 +17,9 @@ See L<Catalyst>.
 
 =head2 $self->match( $c, $path )
 
+Check if there's an index action for a given path, and set it up to use it
+if there is.
+
 =cut
 
 sub match {
diff --git a/lib/Catalyst/DispatchType/Path.pm b/lib/Catalyst/DispatchType/Path.pm
index bd74c79..d887a13 100644
--- a/lib/Catalyst/DispatchType/Path.pm
+++ b/lib/Catalyst/DispatchType/Path.pm
@@ -19,6 +19,8 @@ See L<Catalyst>.
 
 =head2 $self->list($c)
 
+Debug output for Path dispatch points
+
 =cut
 
 sub list {
@@ -35,6 +37,8 @@ sub list {
 
 =head2 $self->match( $c, $path )
 
+Check for paths that match the given path.
+
 =cut
 
 sub match {
@@ -55,6 +59,8 @@ sub match {
 
 =head2 $self->register( $c, $action )
 
+Call register_path for every path attribute in the given $action.
+
 =cut
 
 sub register {
@@ -70,6 +76,8 @@ sub register {
 
 =head2 $self->register_path($c, $path, $action)
 
+register an action at a given path.
+
 =cut
 
 sub register_path {
diff --git a/lib/Catalyst/DispatchType/Regex.pm b/lib/Catalyst/DispatchType/Regex.pm
index 520e038..9470297 100644
--- a/lib/Catalyst/DispatchType/Regex.pm
+++ b/lib/Catalyst/DispatchType/Regex.pm
@@ -18,6 +18,8 @@ See L<Catalyst>.
 
 =head2 $self->list($c)
 
+Output a table of all regex actions, and their private equivalent.
+
 =cut
 
 sub list {
@@ -33,6 +35,9 @@ sub list {
 
 =head2 $self->match( $c, $path )
 
+Check path against compiled regexes, and set action to any matching
+action. Returns 1 on success and 0 on failure.
+
 =cut
 
 sub match {
@@ -59,6 +64,11 @@ sub match {
 
 =head2 $self->register( $c, $action )
 
+Registers one or more regex actions for an action object.\
+Also registers them as literal paths.
+
+Returns 1 on if any regexps were registered.
+
 =cut
 
 sub register {
@@ -77,6 +87,9 @@ sub register {
 
 =head2 $self->register_regex($c, $re, $action)
 
+Register an individual regex on the action. Usually called from the 
+register action.
+
 =cut
 
 sub register_regex {
diff --git a/lib/Catalyst/Dispatcher.pm b/lib/Catalyst/Dispatcher.pm
index 855226a..e74a49d 100644
--- a/lib/Catalyst/Dispatcher.pm
+++ b/lib/Catalyst/Dispatcher.pm
@@ -38,8 +38,15 @@ See L<Catalyst>.
 
 =head1 DESCRIPTION
 
+This is the class that maps public urls to actions in your Catalyst
+application based on the attributes you set.
+
 =head1 METHODS
 
+=item new 
+
+Construct a new dispatcher.
+
 =cut
 
 sub new {
@@ -76,6 +83,8 @@ it with a C<+>, like so:
 
 =head2 $self->detach( $c, $command [, \@arguments ] )
 
+Documented in L<Catalyst>
+
 =cut
 
 sub detach {
@@ -86,6 +95,10 @@ sub detach {
 
 =head2 $self->dispatch($c)
 
+Delegate the dispatch to the action that matched the url, or return a
+message about unknown resource
+
+
 =cut
 
 sub dispatch {
@@ -106,6 +119,8 @@ sub dispatch {
 
 =head2 $self->forward( $c, $command [, \@arguments ] )
 
+Documented in L<Catalyst>
+
 =cut
 
 sub forward {
@@ -206,6 +221,8 @@ qq/Couldn't forward to command "$command". Invalid action or component./;
 
 =head2 $self->prepare_action($c)
 
+Find an dispatch type that matches $c->req->path, and set args from it.
+
 =cut
 
 sub prepare_action {
@@ -244,6 +261,8 @@ sub prepare_action {
 
 =head2 $self->get_action( $action, $namespace )
 
+returns a named action from a given namespace.
+
 =cut
 
 sub get_action {
@@ -278,6 +297,8 @@ sub get_actions {
 
 =head2 $self->get_containers( $namespace )
 
+Return all the action containers for a given namespace, inclusive
+
 =cut
 
 sub get_containers {
@@ -320,6 +341,10 @@ sub get_containers {
 
 =head2 $self->register( $c, $action )
 
+Make sure all required dispatch types for this action are loaded, then
+pass the action to our dispatch types so they can register it if required.
+Also, set up the tree with the action containers.
+
 =cut
 
 sub register {
@@ -378,7 +403,8 @@ sub register {
     $parent->getNodeValue->actions->{ $action->name } = $action;
 }
 
-=head2 $self->setup_actions( $class, $component )
+=head2 $self->setup_actions( $class, $context )
+
 
 =cut
 
diff --git a/lib/Catalyst/Engine.pm b/lib/Catalyst/Engine.pm
index 963ac5a..ff2e797 100644
--- a/lib/Catalyst/Engine.pm
+++ b/lib/Catalyst/Engine.pm
@@ -30,9 +30,6 @@ See L<Catalyst>.
 
 =head1 METHODS
 
-=head2 $self->finalize_output
-
-<obsolete>, see finalize_body
 
 =head2 $self->finalize_body($c)
 
@@ -56,6 +53,8 @@ sub finalize_body {
 
 =head2 $self->finalize_cookies($c)
 
+Create CGI::Cookies from $c->res->cookies, and set them as response headers.
+
 =cut
 
 sub finalize_cookies {
@@ -83,6 +82,10 @@ sub finalize_cookies {
 
 =head2 $self->finalize_error($c)
 
+Output an apropriate error message, called if there's an error in $c
+after the dispatch has finished. Will output debug messages if Catalyst
+is in debug mode, or a `please come back later` message otherwise.
+
 =cut
 
 sub finalize_error {
@@ -263,6 +266,8 @@ EOF
 
 =head2 $self->finalize_headers($c)
 
+Abstract method, allows engines to write headers to response
+
 =cut
 
 sub finalize_headers { }
@@ -279,6 +284,8 @@ sub finalize_read {
 
 =head2 $self->finalize_uploads($c)
 
+Clean up after uploads, deleting temp files.
+
 =cut
 
 sub finalize_uploads {
@@ -296,6 +303,8 @@ sub finalize_uploads {
 
 =head2 $self->prepare_body($c)
 
+sets up the L<Catalyst::Request> object body using L<HTTP::Body>
+
 =cut
 
 sub prepare_body {
@@ -324,6 +333,8 @@ sub prepare_body {
 
 =head2 $self->prepare_body_chunk($c)
 
+Add a chunk to the request body.
+
 =cut
 
 sub prepare_body_chunk {
@@ -334,6 +345,8 @@ sub prepare_body_chunk {
 
 =head2 $self->prepare_body_parameters($c)
 
+Sets up parameters from body. 
+
 =cut
 
 sub prepare_body_parameters {
@@ -343,12 +356,16 @@ sub prepare_body_parameters {
 
 =head2 $self->prepare_connection($c)
 
+Abstract method implemented in engines.
+
 =cut
 
 sub prepare_connection { }
 
 =head2 $self->prepare_cookies($c)
 
+Parse cookies from header. Sets a L<CGI::Cookie> object.
+
 =cut
 
 sub prepare_cookies {
@@ -367,6 +384,8 @@ sub prepare_headers { }
 
 =head2 $self->prepare_parameters($c)
 
+sets up parameters from query and post parameters.
+
 =cut
 
 sub prepare_parameters {
@@ -394,6 +413,8 @@ sub prepare_parameters {
 
 =head2 $self->prepare_path($c)
 
+abstract method, implemented by engines.
+
 =cut
 
 sub prepare_path { }
@@ -402,6 +423,8 @@ sub prepare_path { }
 
 =head2 $self->prepare_query_parameters($c)
 
+process the query string and extract query parameters.
+
 =cut
 
 sub prepare_query_parameters {
@@ -420,6 +443,8 @@ sub prepare_query_parameters {
 
 =head2 $self->prepare_read($c)
 
+prepare to read from the engine.
+
 =cut
 
 sub prepare_read {
@@ -431,6 +456,8 @@ sub prepare_read {
 
 =head2 $self->prepare_request(@arguments)
 
+Populate the context object from the request object.
+
 =cut
 
 sub prepare_request { }
@@ -466,6 +493,8 @@ sub prepare_uploads {
 
 =head2 $self->prepare_write($c)
 
+Abstract method. Implemented by the engines.
+
 =cut
 
 sub prepare_write { }
@@ -523,12 +552,16 @@ The amount of input data that has already been read.
 
 =head2 $self->run($c)
 
+Start the engine. Implemented by the various engine classes.
+
 =cut
 
 sub run { }
 
 =head2 $self->write($c, $buffer)
 
+Writes the buffer to the client. Can only be called once for a request.
+
 =cut
 
 sub write {
@@ -542,6 +575,10 @@ sub write {
     print STDOUT $buffer;
 }
 
+=head2 $self->finalize_output
+
+<obsolete>, see finalize_body
+
 =head1 AUTHORS
 
 Sebastian Riedel, <sri@cpan.org>