From: Matt S Trout <mst@shadowcat.co.uk>
Date: Sun, 4 Jun 2006 14:13:26 +0000 (+0000)
Subject: improved DispatchType docs
X-Git-Tag: 5.7099_04~543
X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?p=catagits%2FCatalyst-Runtime.git;a=commitdiff_plain;h=b2b90ec28d4f51ef6e86e5acc2abb1dc92446147

improved DispatchType docs
---

diff --git a/lib/Catalyst/DispatchType/Default.pm b/lib/Catalyst/DispatchType/Default.pm
index 58779fa..fc734dd 100644
--- a/lib/Catalyst/DispatchType/Default.pm
+++ b/lib/Catalyst/DispatchType/Default.pm
@@ -17,8 +17,12 @@ 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.
+If path is empty (i.e. all path parts have been converted into args),
+attempts to find a default for the namespace constructed from the args,
+or the last inherited default otherwise and will match that.
+
+If path is not empty, never matches since Default will only match if all
+other possibilities have been exhausted.
 
 =cut
 
diff --git a/lib/Catalyst/DispatchType/Index.pm b/lib/Catalyst/DispatchType/Index.pm
index fbe9faa..f99e41c 100644
--- a/lib/Catalyst/DispatchType/Index.pm
+++ b/lib/Catalyst/DispatchType/Index.pm
@@ -18,7 +18,8 @@ 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.
+if there is; only matches a full URI - if $c->req->args is already set
+this DispatchType is guaranteed not to match.
 
 =cut
 
diff --git a/lib/Catalyst/DispatchType/Path.pm b/lib/Catalyst/DispatchType/Path.pm
index c13f73c..0cd698c 100644
--- a/lib/Catalyst/DispatchType/Path.pm
+++ b/lib/Catalyst/DispatchType/Path.pm
@@ -38,7 +38,9 @@ sub list {
 
 =head2 $self->match( $c, $path )
 
-Check for paths that match the given path.
+For each action registered to this exact path, offers the action a chance to
+match the path (in the order in which they were registered). Succeeds on the
+first action that matches, if any; if not, returns 0.
 
 =cut
 
@@ -61,7 +63,7 @@ sub match {
 
 =head2 $self->register( $c, $action )
 
-Call register_path for every path attribute in the given $action.
+Calls register_path for every Path attribute for the given $action.
 
 =cut
 
@@ -78,7 +80,7 @@ sub register {
 
 =head2 $self->register_path($c, $path, $action)
 
-register an action at a given path.
+Registers an action at a given path.
 
 =cut
 
diff --git a/lib/Catalyst/DispatchType/Regex.pm b/lib/Catalyst/DispatchType/Regex.pm
index c40be54..3fbc04c 100644
--- a/lib/Catalyst/DispatchType/Regex.pm
+++ b/lib/Catalyst/DispatchType/Regex.pm
@@ -36,8 +36,10 @@ 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.
+Checks path against every compiled regex, and offers the action for any regex
+which matches a chance to match the request. If it succeeds, sets action,
+match and captures on $c->req and returns 1. If not, returns 0 without
+altering $c.
 
 =cut
 
@@ -65,10 +67,10 @@ sub match {
 
 =head2 $self->register( $c, $action )
 
-Registers one or more regex actions for an action object.\
+Registers one or more regex actions for an action object.
 Also registers them as literal paths.
 
-Returns 1 on if any regexps were registered.
+Returns 1 if any regexps were registered.
 
 =cut
 
@@ -89,7 +91,7 @@ sub register {
 =head2 $self->register_regex($c, $re, $action)
 
 Register an individual regex on the action. Usually called from the 
-register action.
+register method.
 
 =cut