Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

Merge pull request #315 from karenetheridge/topic/201208_docs

grammar, spelling, module links
  • Loading branch information...
commit 6d10096281bd17c195ab8194507342d4e57d0aed 2 parents 931e921 + 6a56ba3
@miyagawa miyagawa authored
View
2  Changes
@@ -3,7 +3,7 @@ Go to http://github.com/plack/Plack/issues for the roadmap and known issues.
1.0001 Thu Jul 26 16:24:13 PDT 2012
[INCOMPATIBLE CHANGES]
- Deleted lots of code, methods and warnings that have been deprecated since 0.99
- (which should've been done in 1.0000 release)
+ (which should have been done in the 1.0000 release)
[DEVELOPERS]
- Added bootstrap script to install devel dependencies
View
14 lib/HTTP/Message/PSGI.pm
@@ -217,11 +217,11 @@ HTTP::Message::PSGI - Converts HTTP::Request and HTTP::Response from/to PSGI env
=head1 DESCRIPTION
-HTTP::Message::PSGI gives you convenient methods convert HTTP::Request
-object to PSGI env hash and convert PSGI response array ref to
-HTTP::Response object.
+HTTP::Message::PSGI gives you convenient methods to convert an L<HTTP::Request>
+object to a PSGI env hash and convert a PSGI response arrayref to
+a L<HTTP::Response> object.
-If you want the other way round, see L<Plack::Request> and
+If you want the other way around, see L<Plack::Request> and
L<Plack::Response>.
=head1 METHODS
@@ -232,7 +232,7 @@ L<Plack::Response>.
my $env = req_to_psgi($req [, $key => $val ... ]);
-Converts HTTP::Request object into PSGI env hash reference.
+Converts a L<HTTP::Request> object into a PSGI env hash reference.
=item HTTP::Request::to_psgi
@@ -244,13 +244,13 @@ Same as C<req_to_psgi> but an instance method in L<HTTP::Request>.
my $res = res_from_psgi([ $status, $headers, $body ]);
-Creates HTTP::Response object from PSGI response array ref.
+Creates a L<HTTP::Response> object from a PSGI response array ref.
=item HTTP::Response->from_psgi
my $res = HTTP::Response->from_psgi([ $status, $headers, $body ]);
-Same as C<res_from_psgi> but a class method in L<HTTP::Response>.
+Same as C<res_from_psgi>, but is a class method in L<HTTP::Response>.
=back
View
13 lib/Plack/App/URLMap.pm
@@ -105,7 +105,7 @@ Plack::App::URLMap is a PSGI application that can dispatch multiple
applications based on URL path and hostnames (a.k.a "virtual hosting")
and takes care of rewriting C<SCRIPT_NAME> and C<PATH_INFO> (See
L</"HOW THIS WORKS"> for details). This module is inspired by
-Rack::URLMap.
+Ruby's Rack::URLMap.
=head1 METHODS
@@ -117,14 +117,15 @@ Rack::URLMap.
$urlmap->map("http://bar.example.com/" => $another_app);
Maps URL path or an absolute URL to a PSGI application. The match
-order is sorted by host name length and then path length.
+order is sorted by host name length and then path length (longest strings
+first).
URL paths need to match from the beginning and should match completely
-till the path separator (or the end of the path). For example, if you
-register the path C</foo>, it B<will> match with the request C</foo>,
-C</foo/> or C</foo/bar> but it B<won't> match with C</foox>.
+until the path separator (or the end of the path). For example, if you
+register the path C</foo>, it I<will> match with the request C</foo>,
+C</foo/> or C</foo/bar> but it I<won't> match with C</foox>.
-Mapping URL with host names is also possible, and in that case the URL
+Mapping URLs with host names is also possible, and in that case the URL
mapping works like a virtual host.
Mappings will nest. If $app is already mapped to C</baz> it will
View
22 lib/Plack/Builder.pm
@@ -154,13 +154,13 @@ Plack::Builder - OO and DSL to enable Plack Middlewares
=head1 DESCRIPTION
Plack::Builder gives you a quick domain specific language (DSL) to
-wrap your application with Plack::Middleware subclasses. The
+wrap your application with L<Plack::Middleware> subclasses. The
middleware you're trying to use should use L<Plack::Middleware> as a
base class to use this DSL, inspired by Rack::Builder.
Whenever you call C<enable> on any middleware, the middleware app is
pushed to the stack inside the builder, and then reversed when it
-actually creates a wrapped application handler. "Plack::Middleware::"
+actually creates a wrapped application handler. C<"Plack::Middleware::">
is added as a prefix by default. So:
builder {
@@ -182,8 +182,8 @@ Plack::Builder allows you to code middleware inline using a nested
code reference.
If the first argument to C<enable> is a code reference, it will be
-passed an C<$app> and is supposed to return another code reference
-which is PSGI application that consumes C<$env> in runtime. So:
+passed an C<$app> and should return another code reference
+which is a PSGI application that consumes C<$env> at runtime. So:
builder {
enable sub {
@@ -210,7 +210,7 @@ is equal to:
=head1 URLMap support
-Plack::Builder has a native support for L<Plack::App::URLMap> with C<mount> method.
+Plack::Builder has a native support for L<Plack::App::URLMap> via the C<mount> method.
use Plack::Builder;
my $app = builder {
@@ -222,7 +222,7 @@ Plack::Builder has a native support for L<Plack::App::URLMap> with C<mount> meth
};
See L<Plack::App::URLMap>'s C<map> method to see what they mean. With
-builder you can't use C<map> as a DSL, for the obvious reason :)
+C<builder> you can't use C<map> as a DSL, for the obvious reason :)
B<NOTE>: Once you use C<mount> in your builder code, you have to use
C<mount> for all the paths, including the root path (C</>). You can't
@@ -255,12 +255,12 @@ Note that the C<builder> DSL returns a whole new PSGI application, which means
C<builder { ... }> should normally the last statement of a C<.psgi>
file, because the return value of C<builder> is the application that
-actually is executed.
+is actually executed.
=item *
-You can nest your C<builder> block, mixed with C<mount> (see URLMap
-support above):
+You can nest your C<builder> blocks, mixed with C<mount> statements (see L</"URLMap support">
+above):
builder {
mount "/foo" => builder {
@@ -268,8 +268,8 @@ support above):
}
}
-will locate the C<$app> under C</foo/bar> since the inner C<builder>
-block puts it under C</bar> and it results a new PSGI application
+will locate the C<$app> under C</foo/bar>, since the inner C<builder>
+block puts it under C</bar> and it results in a new PSGI application
which is located under C</foo> because of the outer C<builder> block.
=back
View
10 lib/Plack/Component.pm
@@ -70,8 +70,8 @@ Plack::Component - Base class for PSGI endpoints
=head1 DESCRIPTION
-Plack::Component is the base class shared between Plack::Middleware
-and Plack::App::* modules. If you are writing middleware, you should
+Plack::Component is the base class shared between L<Plack::Middleware>
+and C<Plack::App::*> modules. If you are writing middleware, you should
inherit from L<Plack::Middleware>, but if you are writing a
Plack::App::* you should inherit from this directly.
@@ -93,8 +93,8 @@ as an argument and is expected to return a proper PSGI response value.
=item new (%opts | \%opts)
-The constructor accepts either a hash or a hash-ref and uses that to
-create the instance with. It will call no other methods and simply return
+The constructor accepts either a hash or a hashref and uses that to
+create the instance. It will call no other methods and simply return
the instance that is created.
=item prepare_app
@@ -106,7 +106,7 @@ prepare your component before it is packaged as a PSGI C<$app>.
This is the method used in several parts of the Plack infrastructure to
convert your component into a PSGI C<$app>. You should not ever need to
-override this method, it is recommended to use C<prepare_app> and C<call>
+override this method; it is recommended to use C<prepare_app> and C<call>
instead.
=item response_cb
View
17 lib/Plack/Middleware.pm
@@ -55,11 +55,11 @@ Plack::Middleware - Base class for easy-to-use PSGI middleware
Plack::Middleware is a utility base class to write PSGI
middleware. All you have to do is to inherit from Plack::Middleware
-and then implement the callback C<call> method (or C<to_app> method
+and then implement the callback C<call> method (or the C<to_app> method
that would return the PSGI code reference) to do the actual work. You
can use C<< $self->app >> to call the original (wrapped) application.
-Your middleware object is created at a PSGI application compile time
+Your middleware object is created at the the PSGI application compile time
and is persistent during the web server life cycle (unless it is a
non-persistent environment such as CGI), so you should never set or
cache per-request data like C<$env> in your middleware object. See
@@ -67,7 +67,7 @@ also L<Plack::Component/"OBJECT LIFECYCLE">.
See L<Plack::Builder> how to actually enable middleware in your
I<.psgi> application file using the DSL. If you do not like our
-builder DSL, you can also use C<wrap> method to wrap your application
+builder DSL, you can also use the C<wrap> method to wrap your application
with a middleware:
use Plack::Middleware::Foo;
@@ -91,7 +91,7 @@ The typical middleware is written like this:
return $res;
}
-The tricky thing about post processing the response is that it could
+The tricky thing about post-processing the response is that it could
either be an immediate 3 element array ref, or a code reference that
implements the delayed (streaming) interface.
@@ -107,8 +107,7 @@ middleware.
});
The callback function gets a PSGI response as a 3 element array
-reference, and you can update the reference to implement the post
-processing.
+reference, and you can update the reference to implement the post-processing.
package Plack::Middleware::Always500;
use parent qw(Plack::Middleware);
@@ -152,9 +151,9 @@ do:
return;
});
-The third element of PSGI response array ref is a body, and it could
-be either array ref or IO::Handle-ish object. The application could
-also make use of C<$writer> object if C<psgi.streaming> is in
+The third element of the PSGI response array ref is a body, and it could
+be either an arrayref or L<IO::Handle>-ish object. The application could
+also make use of the C<$writer> object if C<psgi.streaming> is in
effect. Dealing with these variants is again really painful, and
C<response_cb> can take care of that too, by allowing you to return a
content filter as a code reference.
View
6 lib/Plack/Middleware/AccessLog.pm
@@ -134,8 +134,8 @@ can be specified using Apache-like format strings (or C<combined> or
C<common> for the default formats). If none is specified C<combined> is
used.
-This middleware uses calculable content-length by checking body type,
-and can not log the time taken to serve requests. It also logs the
+This middleware uses calculable Content-Length by checking body type,
+and cannot log the time taken to serve requests. It also logs the
request B<before> the response is actually sent to the client. Use
L<Plack::Middleware::AccessLog::Timed> if you want to log details
B<after> the response is transmitted (more like a real web server) to
@@ -185,7 +185,7 @@ with one of the mandatory modifier flags C<i>, C<o> or C<t>:
enable "Plack::Middleware::AccessLog",
logger => sub { $logger->log(level => 'debug', message => @_) };
-Sets a callback to print log message to. It prints to C<psgi.errors>
+Sets a callback to print log message to. It prints to the C<psgi.errors>
output stream by default.
=back
View
14 lib/Plack/Middleware/Log4perl.pm
@@ -59,8 +59,8 @@ Plack::Middleware::Log4perl - Uses Log::Log4perl to configure logger
=head1 DESCRIPTION
-Log4perl is a Plack::Middleware component that allows you to use
-L<Log::Log4perl> to configure logging object.
+Log4perl is a L<Plack::Middleware> component that allows you to use
+L<Log::Log4perl> to configure the logging object, C<psgix.logger>.
=head1 CONFIGURATION
@@ -68,13 +68,13 @@ L<Log::Log4perl> to configure logging object.
=item category
-The log4perl category to send logs to. Defaults to C<''> which means
+The C<log4perl> category to send logs to. Defaults to C<''> which means
it send to the root logger.
=item conf
The configuration file path (or a scalar ref containing the config
-string) for Log::Log4perl to automatically configure.
+string) for L<Log::Log4perl> to automatically configure.
=back
@@ -84,7 +84,11 @@ Tatsuhiko Miyagawa
=head1 SEE ALSO
-L<Log::Dispatch>
+L<Log::Log4perl>
+
+L<Plack::Middleware::LogDispatch>
+
+L<Plack::Middleware::Log::Contextual>
=cut
View
9 lib/Plack/Middleware/LogDispatch.pm
@@ -55,8 +55,8 @@ Plack::Middleware::LogDispatch - Uses Log::Dispatch to configure logger
=head1 DESCRIPTION
-LogDispatch is a Plack::Middleware component that allows you to use
-L<Log::Dispatch> to configure logging object.
+LogDispatch is a L<Plack::Middleware> component that allows you to use
+L<Log::Dispatch> to configure the logging object, C<psgix.logger>.
=head1 CONFIGURATION
@@ -64,7 +64,7 @@ L<Log::Dispatch> to configure logging object.
=item logger
-Log::Dispatch object to send logs to. Required.
+L<Log::Dispatch> object to send logs to. Required.
=back
@@ -76,5 +76,8 @@ Tatsuhiko Miyagawa
L<Log::Dispatch>
+L<Plack::Middleware::Log4perl>
+
+L<Plack::Middleware::Log::Contextual>
=cut
View
2  lib/Plack/Middleware/Runtime.pm
@@ -33,7 +33,7 @@ Plack::Middleware::Runtime - Sets an X-Runtime response header
=head1 DESCRIPTION
Plack::Middleware::Runtime is a Plack middleware component that sets
-application's response time, in seconds to I<X-Runtime> HTTP response
+the application's response time (in seconds) in the I<X-Runtime> HTTP response
header.
=head1 OPTIONS
Please sign in to comment.
Something went wrong with that request. Please try again.