Clarify wording

[catagits/Catalyst-Runtime.git] / lib / Catalyst.pm

diff --git a/lib/Catalyst.pm b/lib/Catalyst.pm
index 1d51d26..a3d8f9e 100644 (file)
--- a/lib/Catalyst.pm
+++ b/lib/Catalyst.pm
@@ -84,7 +84,7 @@ __PACKAGE__->stats_class('Catalyst::Stats');
 
 # Remember to update this in Catalyst::Runtime as well!
 
-our $VERSION = '5.90004';
+our $VERSION = '5.90005';
 
 sub import {
     my ( $class, @arguments ) = @_;
@@ -202,7 +202,7 @@ fully qualify the name by using a unary plus:
         +Fully::Qualified::Plugin::Name
     /;
 
-Special flags like C<-Debug> and C<-Engine> can also be specified as
+Special flags like C<-Debug> can also be specified as
 arguments when Catalyst is loaded:
 
     use Catalyst qw/-Debug My::Module/;
@@ -222,13 +222,6 @@ priority.
 This sets the log level to 'debug' and enables full debug output on the
 error screen. If you only want the latter, see L<< $c->debug >>.
 
-=head2 -Engine
-
-Forces Catalyst to use a specific engine. Omit the
-C<Catalyst::Engine::> prefix of the engine name, i.e.:
-
-    use Catalyst qw/-Engine=CGI/;
-
 =head2 -Home
 
 Forces Catalyst to use a specific home directory, e.g.:
@@ -1002,26 +995,11 @@ sub path_to {
     else { return Path::Class::File->new( $c->config->{home}, @path ) }
 }
 
-=head2 $c->plugin( $name, $class, @args )
-
-Helper method for plugins. It creates a class data accessor/mutator and
-loads and instantiates the given class.
-
-    MyApp->plugin( 'prototype', 'HTML::Prototype' );
-
-    $c->prototype->define_javascript_functions;
-
-B<Note:> This method of adding plugins is deprecated. The ability
-to add plugins like this B<will be removed> in a Catalyst 5.81.
-Please do not use this functionality in new code.
-
-=cut
-
 sub plugin {
     my ( $class, $name, $plugin, @args ) = @_;
 
     # See block comment in t/unit_core_plugin.t
-    $class->log->warn(qq/Adding plugin using the ->plugin method is deprecated, and will be removed in Catalyst 5.81/);
+    $class->log->warn(qq/Adding plugin using the ->plugin method is deprecated, and will be removed in a future release/);
 
     $class->_register_plugin( $plugin, 1 );
 
@@ -1050,6 +1028,9 @@ Catalyst> line.
     MyApp->setup;
     MyApp->setup( qw/-Debug/ );
 
+B<Note:> You B<should not> wrap this method with method modifiers
+or bad things will happen - wrap the C<setup_finalize> method instead.
+
 =cut
 
 sub setup {
@@ -1373,9 +1354,9 @@ sub uri_for {
     $res;
 }
 
-=head2 $c->uri_for_action( $path, \@captures?, @args?, \%query_values? )
+=head2 $c->uri_for_action( $path, \@captures_and_args?, @args?, \%query_values? )
 
-=head2 $c->uri_for_action( $action, \@captures?, @args?, \%query_values? )
+=head2 $c->uri_for_action( $action, \@captures_and_args?, @args?, \%query_values? )
 
 =over
 
@@ -1404,6 +1385,31 @@ You can use:
 
 and it will create the URI /users/the-list.
 
+=item \@captures_and_args?
+
+Optional array reference of Captures (i.e. C<<CaptureArgs or $c->req->captures>)
+and arguments to the request. Usually used with L<Catalyst::DispatchType::Chained>
+to interpolate all the parameters in the URI.
+
+=item @args?
+
+Optional list of extra arguments - can be supplied in the
+C<< \@captures_and_args? >> array ref, or here - whichever is easier for your
+code.
+
+Your action can have zero, a fixed or a variable number of args (e.g.
+C<< Args(1) >> for a fixed number or C<< Args() >> for a variable number)..
+
+=item \%query_values?
+
+Optional array reference of query parameters to append. E.g.
+
+  { foo => 'bar' }
+
+will generate
+
+  /rest/of/your/uri?foo=bar
+
 =back
 
 =cut
@@ -2843,7 +2849,7 @@ sub setup_stats {
 =head2 $c->registered_plugins
 
 Returns a sorted list of the plugins which have either been stated in the
-import list or which have been added via C<< MyApp->plugin(@args); >>.
+import list.
 
 If passed a given plugin name, it will report a boolean value indicating
 whether or not that plugin is loaded.  A fully qualified name is required if
@@ -3035,7 +3041,7 @@ to be shown in hit debug tables in the test server.
 
 =item *
 
-C<use_request_uri_for_path> - Controlls if the C<REQUEST_URI> or C<PATH_INFO> environment
+C<use_request_uri_for_path> - Controls if the C<REQUEST_URI> or C<PATH_INFO> environment
 variable should be used for determining the request path. 
 
 Most web server environments pass the requested path to the application using environment variables,
@@ -3050,7 +3056,7 @@ is determined by the C<< $c->config(use_request_uri_for_path) >> setting (which
 =item use_request_uri_for_path => 0
 
 This is the default (and the) traditional method that Catalyst has used for determining the path information.
-The path is synthesised from a combination of the C<PATH_INFO> and C<SCRIPT_NAME> environment variables.
+The path is generated from a combination of the C<PATH_INFO> and C<SCRIPT_NAME> environment variables.
 The allows the application to behave correctly when C<mod_rewrite> is being used to redirect requests
 into the application, as these variables are adjusted by mod_rewrite to take account for the redirect.