From: Marcus Ramberg <marcus@nordaaker.com>
Date: Sun, 19 Nov 2006 21:47:20 +0000 (+0000)
Subject: refactored to leave synopsis to the top, and move the rest of the pod to the
X-Git-Tag: 5.7099_04~263
X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=b2ddf6d7e1ea8f9b281ce5da27ecadf3152e151d;hp=837844227499d9317fbb8aad7b433fcb159b4b3a;p=catagits%2FCatalyst-Runtime.git

refactored to leave synopsis to the top, and move the rest of the pod to the
bottom
---

diff --git a/lib/Catalyst/Action.pm b/lib/Catalyst/Action.pm
index 0ddd796..a4f5eb4 100644
--- a/lib/Catalyst/Action.pm
+++ b/lib/Catalyst/Action.pm
@@ -3,6 +3,24 @@ package Catalyst::Action;
 use strict;
 use base qw/Class::Accessor::Fast/;
 
+
+=head1 NAME
+
+Catalyst::Action - Catalyst Action
+
+=head1 SYNOPSIS
+
+	<form action="[%c.uri_for(c.action.reverse)%]">
+	
+=head1 DESCRIPTION
+
+This class represents a Catalyst Action. You can access the object for the 
+currently dispatched action via $c->action. See the L<Catalyst::Dispatcher>
+for more information on how actions are dispatched. Actions are defined in
+L<Catalyst::Controller> subclasses.
+
+=cut
+
 __PACKAGE__->mk_accessors(qw/class namespace reverse attributes name code/);
 
 use overload (
@@ -18,71 +36,57 @@ use overload (
 
 );
 
-=head1 NAME
-
-Catalyst::Action - Catalyst Action
+sub dispatch {    # Execute ourselves against a context
+    my ( $self, $c ) = @_;
+    local $c->namespace = $self->namespace;
+    return $c->execute( $self->class, $self );
+}
 
-=head1 SYNOPSIS
+sub execute {
+  my $self = shift;
+  $self->{code}->(@_);
+}
 
-See L<Catalyst>.
+sub match {
+    my ( $self, $c ) = @_;
+    return 1 unless exists $self->attributes->{Args};
+    my $args = $self->attributes->{Args}[0];
+    return 1 unless defined($args) && length($args);
+    return scalar( @{ $c->req->args } ) == $args;
+}
 
-=head1 DESCRIPTION
+1;
 
-This class represents a Catalyst Action. You can access the object for the 
-currently dispatched action via $c->action
+__END__
 
 =head1 METHODS
 
 =head2 attributes
 
 The sub attributes that are set for this action, like Local, Path, Private
-and so on.
+and so on. This determines how the action is dispatched to.
 
 =head2 class
 
-Returns the class name of this action
+Returns the class name where this action is defined.
 
 =head2 code
 
-Returns a code reference to this action
+Returns a code reference to this action.
 
 =head2 dispatch( $c )
 
 Dispatch this action against a context
 
-=cut
-
-sub dispatch {    # Execute ourselves against a context
-    my ( $self, $c ) = @_;
-    local $c->namespace = $self->namespace;
-    return $c->execute( $self->class, $self );
-}
-
 =head2 execute( $controller, $c, @args )
 
 Execute this action's coderef against a given controller with a given
 context and arguments
 
-=cut
-
-sub execute {
-  my $self = shift;
-  $self->{code}->(@_);
-}
-
 =head2 match( $c )
 
 Check Args attribute, and makes sure number of args matches the setting.
-
-=cut
-
-sub match {
-    my ( $self, $c ) = @_;
-    return 1 unless exists $self->attributes->{Args};
-    my $args = $self->attributes->{Args}[0];
-    return 1 unless defined($args) && length($args);
-    return scalar( @{ $c->req->args } ) == $args;
-}
+Always returns true if Args is omitted.
 
 =head2 namespace
 
@@ -105,6 +109,4 @@ Matt S. Trout
 This program is free software, you can redistribute it and/or modify it under
 the same terms as Perl itself.
 
-=cut
-
-1;
+=cut
\ No newline at end of file
diff --git a/lib/Catalyst/ActionChain.pm b/lib/Catalyst/ActionChain.pm
index 6d16104..2fd63d9 100644
--- a/lib/Catalyst/ActionChain.pm
+++ b/lib/Catalyst/ActionChain.pm
@@ -3,20 +3,6 @@ package Catalyst::ActionChain;
 use strict;
 use base qw/Catalyst::Action/;
 
-__PACKAGE__->mk_accessors(qw/chain/);
-
-use overload (
-
-    # Stringify to reverse for debug output etc.
-    q{""} => sub { shift->{reverse} },
-
-    # Codulate to execute to invoke the encapsulated action coderef
-    '&{}' => sub { my $self = shift; sub { $self->execute(@_); }; },
-
-    # Make general $stuff still work
-    fallback => 1,
-
-);
 
 =head1 NAME
 
@@ -24,7 +10,7 @@ Catalyst::ActionChain - Chain of Catalyst Actions
 
 =head1 SYNOPSIS
 
-See L<Catalyst>.
+See L<Catalyst::Manual::Intro> for more info about Chained actions.
 
 =head1 DESCRIPTION
 
@@ -32,19 +18,23 @@ This class represents a chain of Catalyst Actions. It behaves exactly like
 the action at the *end* of the chain except on dispatch it will execute all
 the actions in the chain in order.
 
-=head1 METHODS
+=cut
 
-=head2 chain
+__PACKAGE__->mk_accessors(qw/chain/);
 
-Accessor for the action chain; will be an arrayref of the Catalyst::Action
-objects encapsulated by this chain.
+use overload (
 
-=head2 dispatch( $c )
+    # Stringify to reverse for debug output etc.
+    q{""} => sub { shift->{reverse} },
 
-Dispatch this action chain against a context; will dispatch the encapsulated
-actions in order.
+    # Codulate to execute to invoke the encapsulated action coderef
+    '&{}' => sub { my $self = shift; sub { $self->execute(@_); }; },
+
+    # Make general $stuff still work
+    fallback => 1,
+
+);
 
-=cut
 
 sub dispatch {
     my ( $self, $c ) = @_;
@@ -62,6 +52,28 @@ sub dispatch {
     $last->dispatch( $c );
 }
 
+sub from_chain {
+    my ( $self, $actions ) = @_;
+    my $final = $actions->[-1];
+    return $self->new({ %$final, chain => $actions });
+}
+
+1;
+
+__END__
+
+=head1 METHODS
+
+=head2 chain
+
+Accessor for the action chain; will be an arrayref of the Catalyst::Action
+objects encapsulated by this chain.
+
+=head2 dispatch( $c )
+
+Dispatch this action chain against a context; will dispatch the encapsulated
+actions in order.
+
 =head2 from_chain( \@actions )
 
 Takes a list of Catalyst::Action objects and constructs and returns a
@@ -69,12 +81,6 @@ Catalyst::ActionChain object representing a chain of these actions
 
 =cut
 
-sub from_chain {
-    my ( $self, $actions ) = @_;
-    my $final = $actions->[-1];
-    return $self->new({ %$final, chain => $actions });
-}
-
 =head1 AUTHOR
 
 Matt S. Trout
@@ -85,5 +91,3 @@ This program is free software, you can redistribute it and/or modify it under
 the same terms as Perl itself.
 
 =cut
-
-1;
diff --git a/lib/Catalyst/ActionContainer.pm b/lib/Catalyst/ActionContainer.pm
index 258cb15..63b8fc9 100644
--- a/lib/Catalyst/ActionContainer.pm
+++ b/lib/Catalyst/ActionContainer.pm
@@ -3,6 +3,21 @@ package Catalyst::ActionContainer;
 use strict;
 use base qw/Class::Accessor::Fast/;
 
+=head1 NAME
+
+Catalyst::ActionContainer - Catalyst Action Container
+
+=head1 SYNOPSIS
+
+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.
+
+=cut
+
 __PACKAGE__->mk_accessors(qw/part actions/);
 
 use overload (
@@ -20,18 +35,23 @@ sub new {
     $class->SUPER::new($fields);
 }
 
-=head1 NAME
 
-Catalyst::ActionContainer - Catalyst Action Container
 
-=head1 SYNOPSIS
+sub get_action {
+    my ( $self, $name ) = @_;
+    return $self->actions->{$name} if defined $self->actions->{$name};
+    return;
+}
 
-See L<Catalyst>.
+sub add_action {
+    my ( $self, $action, $name ) = @_;
+    $name ||= $action->name;
+    $self->actions->{$name} = $action;
+}
 
-=head1 DESCRIPTION
+1;
 
-This is a container for actions. The dispatcher sets up a tree of these
-to represent the various dispatch points in your application.
+__END__
 
 =head1 METHODS
 
@@ -45,26 +65,10 @@ hashref to be populated via add_action later
 
 Returns an action from this container based on the action name, or undef
 
-=cut
-
-sub get_action {
-    my ( $self, $name ) = @_;
-    return $self->actions->{$name} if defined $self->actions->{$name};
-    return;
-}
-
 =head2 add_action($action, [ $name ])
 
 Adds an action, optionally providing a name to override $action->name
 
-=cut
-
-sub add_action {
-    my ( $self, $action, $name ) = @_;
-    $name ||= $action->name;
-    $self->actions->{$name} = $action;
-}
-
 =head2 actions
 
 Accessor to the actions hashref, containing all actions in this container.
@@ -76,7 +80,7 @@ stringifies to.
 
 =head1 AUTHOR
 
-Matt S. Trout
+Matt S. Trout 
 
 =head1 COPYRIGHT