From: Matt S Trout <mst@shadowcat.co.uk>
Date: Sat, 22 Oct 2005 02:37:53 +0000 (+0000)
Subject: - Added some docs to dispatcher modifications
X-Git-Tag: 5.7099_04~1144
X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?p=catagits%2FCatalyst-Runtime.git;a=commitdiff_plain;h=90ce41baee38f4a03bdca90635bf8a75bfbea63e;hp=51f97d147ab4a19a44b578d5f294c6bbfeccba72

- Added some docs to dispatcher modifications
---

diff --git a/lib/Catalyst/Dispatcher.pm b/lib/Catalyst/Dispatcher.pm
index 1b8dfa7..ea9a550 100644
--- a/lib/Catalyst/Dispatcher.pm
+++ b/lib/Catalyst/Dispatcher.pm
@@ -51,6 +51,12 @@ sub dispatch {
         my @containers = $self->get_containers( $c->namespace );
         my %actions;
         foreach my $name (qw/begin auto end/) {
+
+            # Go down the container list representing each part of the
+            # current namespace inheritance tree, grabbing the actions hash
+            # of the ActionContainer object and looking for actions of the
+            # appropriate name registered to the namespace
+
             $actions{$name} = [
                 map { $_->{$name} }
                 grep { exists $_->{$name} }
@@ -302,8 +308,13 @@ sub get_action {
 sub get_containers {
     my ( $self, $namespace ) = @_;
 
+    # If the namespace is / just return the root ActionContainer
+
     return ($self->tree->getNodeValue) if $namespace eq '/';
 
+    # Use a visitor to recurse down the tree finding the ActionContainers
+    # for each namespace in the chain.
+
     my $visitor = Tree::Simple::Visitor::FindByPath->new;
     my @path = split('/', $namespace);
     $visitor->setSearchPath( @path );
@@ -313,6 +324,14 @@ sub get_containers {
     @match = ($self->tree) unless @match;
 
     if (!defined $visitor->getResult) {
+
+        # If we don't manage to match, the visitor doesn't return the last
+        # node is matched, so foo/bar/baz would only find the 'foo' node,
+        # not the foo and foo/bar nodes as it should. This does another
+        # single-level search to see if that's the case, and the 'last unless'
+        # should catch any failures - or short-circuit this if this *is* a
+        # bug in the visitor and gets fixed.
+
         my $extra = $path[(scalar @match) - 1];
         last unless $extra;
         $visitor->setSearchPath($extra);
@@ -366,6 +385,10 @@ sub set_action {
             my $child = $visitor->getResult;
     
             unless ($child) {
+
+                # Create a new tree node and an ActionContainer to form
+                # its value.
+
                 my $container = Catalyst::ActionContainer->new(
                                     { part => $part, actions => {} });
                 $child = $parent->addChild( Tree::Simple->new($container) );
@@ -389,6 +412,7 @@ sub set_action {
         }
     );
 
+    # Set the method value
     $parent->getNodeValue->actions->{$method} = $action;
 
     my @path;