lots of new docs,

default behavior for $c->controller/view/model

diff --git a/Changes b/Changes
index 63193d8..a340fbe 100644 (file)
--- a/Changes
+++ b/Changes
@@ -1,5 +1,11 @@
 This file documents the revision history for Perl extension Catalyst.
 
+5.67   
+       - Looping and recursion tests plus a fix
+       - Added lots of API documentation.
+       - Changed default behaviors for $c->model/$c->controller/$c->view
+         to more sane settings.
+
 5.66    2006-03-10 17:48:00
         - Added Test::WWW::Mechanize::Catalyst support
         - Cleaned generated tests

diff --git a/lib/Catalyst.pm b/lib/Catalyst.pm
index a43be27..6decfd1 100644 (file)
--- a/lib/Catalyst.pm
+++ b/lib/Catalyst.pm
@@ -399,6 +399,17 @@ sub _comp_prefixes {
     return $comp;
 }
 
+# Return a component if only one matches.
+sub _comp_singular {
+    my ($c, @prefixes) = @_;
+
+    my $appclass = ref $c || $c;
+
+    my ($comp,$rest) = map { $c->_comp_search("^${appclass}::${_}::") } 
+       @prefixes;
+    return $comp unless $rest;
+}
+
 =head2 COMPONENT ACCESSORS
 
 =head2 $c->comp($name)
@@ -443,11 +454,15 @@ Gets a L<Catalyst::Controller> instance by name.
 
     $c->controller('Foo')->do_stuff;
 
+If name is omitted, will return the controller for the dispatched action.
+
 =cut
 
 sub controller {
     my ( $c, $name ) = @_;
-    return $c->_comp_prefixes($name, qw/Controller C/);
+    return $c->_comp_prefixes($name, qw/Controller C/)
+       if ($name);
+    return $c->component($c->action->class);
 }
 
 =head2 $c->model($name)
@@ -456,11 +471,19 @@ Gets a L<Catalyst::Model> instance by name.
 
     $c->model('Foo')->do_stuff;
 
+If the name is omitted, it will look for a config setting 'default_model',
+or check if there is only one model, and forward to it if that's the case.
+
 =cut
 
 sub model {
     my ( $c, $name ) = @_;
-    return $c->_comp_prefixes($name, qw/Model M/);
+    return $c->_comp_prefixes($name, qw/Model M/)
+       if $name;
+    return $c->comp($c->config->{default_model})
+       if $c->config->{default_model};
+    return $c->_comp_singular(qw/Model M/);
+
 }
 
 =head2 $c->view($name)
@@ -469,11 +492,18 @@ Gets a L<Catalyst::View> instance by name.
 
     $c->view('Foo')->do_stuff;
 
+If the name is omitted, it will look for a config setting 'default_view',
+or check if there is only one view, and forward to it if that's the case.
+
 =cut
 
 sub view {
     my ( $c, $name ) = @_;
-    return $c->_comp_prefixes($name, qw/View V/);
+    return $c->_comp_prefixes($name, qw/View V/)
+       if $name;
+    return $c->comp($c->config->{default_view})
+       if $c->config->{default_view};
+    return $c->_comp_singular(qw/View V/);
 }
 
 =head2 Class data and helper classes

diff --git a/lib/Catalyst/Action.pm b/lib/Catalyst/Action.pm
index ca695c4..0e132f5 100644 (file)
--- a/lib/Catalyst/Action.pm
+++ b/lib/Catalyst/Action.pm
@@ -46,7 +46,7 @@ Returns the class name of this action
 
 Returns a code reference to this action
 
-=head2 execute <c>
+=head2 execute( $c )
 
 Execute this action against a context
 
@@ -58,9 +58,9 @@ sub execute {    # Execute ourselves against a context
     return $c->execute( $self->class, $self );
 }
 
-=head2 match <context>
+=head2 match( $c )
 
-Check Args setting, and makes sure number of args matches the setting.
+Check Args attribute, and makes sure number of args matches the setting.
 
 =cut
 

diff --git a/lib/Catalyst/ActionContainer.pm b/lib/Catalyst/ActionContainer.pm
index 4dd4500..6b3f282 100644 (file)
--- a/lib/Catalyst/ActionContainer.pm
+++ b/lib/Catalyst/ActionContainer.pm
@@ -22,9 +22,14 @@ See L<Catalyst>.
 
 =head1 DESCRIPTION
 
+This is a container for actions. The dispatcher sets up a tree of these
+to represent the various dispatch points in your application.
+
 =head1 METHODS
 
-=head2 get_action
+=head2 get_action($name)
+
+Returns an action from this container based on the action name, or undef
 
 =cut
 
@@ -36,8 +41,13 @@ sub get_action {
 
 =head2 actions
 
+Accessor to the actions hashref, containing all actions in this container.
+
 =head2 part
 
+Accessor to the path part this container resolves to. Also what the container
+stringifies to.
+
 =head1 AUTHOR
 
 Matt S. Trout

diff --git a/lib/Catalyst/AttrContainer.pm b/lib/Catalyst/AttrContainer.pm
index fecfdcd..ba46cc1 100644 (file)
--- a/lib/Catalyst/AttrContainer.pm
+++ b/lib/Catalyst/AttrContainer.pm
@@ -29,12 +29,19 @@ Catalyst::AttrContainer
 
 =head1 DESCRIPTION
 
+This class sets up the code attribute cache.  It's a base class for 
+L<Catalyst::Base>
+
 =head1 METHODS
 
 =head2 FETCH_CODE_ATTRIBUTES
 
+Attribute function. See attributes(3pm)
+
 =head2 MODIFY_CODE_ATTRIBUTES
 
+Attribute function. See attributes(3pm)
+
 =head1 SEE ALSO
 
 L<Catalyst>.

diff --git a/lib/Catalyst/Base.pm b/lib/Catalyst/Base.pm
index 7536dc6..18e6f6e 100644 (file)
--- a/lib/Catalyst/Base.pm
+++ b/lib/Catalyst/Base.pm
@@ -72,10 +72,15 @@ See L<Catalyst>
 
 Catalyst Base Class
 
+This is the base class for all Catalyst components. It also handles 
+dispatch of actions for controllers.
+
 =head1 METHODS
 
 =head2 $self->action_namespace($c)
 
+Determine the namespace for actions in this component.
+
 =cut
 
 sub action_namespace {
@@ -88,12 +93,16 @@ sub action_namespace {
 
 =head2 $self->path_prefix($c)
 
+alias for action_namespace
+
 =cut
 
 sub path_prefix { shift->action_namespace(@_); }
 
 =head2 $self->register_actions($c)
 
+register all actions for this component based on a given context.
+
 =cut
 
 sub register_actions {

diff --git a/lib/Catalyst/Build.pm b/lib/Catalyst/Build.pm
index ab6ba53..944d9e8 100644 (file)
--- a/lib/Catalyst/Build.pm
+++ b/lib/Catalyst/Build.pm
@@ -31,7 +31,8 @@ L<Module::Build> extension for Catalyst.
 
 =head1 DEPRECATION NOTICE
 
-This module is deprecated in favor of L<Module::Install::Catalyst>.
+This module is deprecated in favor of L<Module::Install::Catalyst>. It's
+only left here for compability with older applications.
 
 =head1 METHODS