From 7b5df7a93cd3cd3c7fcf0a1e9a8a4ff29a19622d Mon Sep 17 00:00:00 2001
From: chromatic <chromatic@wgz.org>
Date: Mon, 19 Sep 2011 12:11:39 -0700
Subject: [PATCH] Clarified documentation.

---
 lib/Plack/Test.pm | 34 ++++++++++++++++++----------------
 1 file changed, 18 insertions(+), 16 deletions(-)

diff --git a/lib/Plack/Test.pm b/lib/Plack/Test.pm
index ed7a60aa4..ec41c13e5 100644
--- a/lib/Plack/Test.pm
+++ b/lib/Plack/Test.pm
@@ -36,7 +36,7 @@ Plack::Test - Test PSGI applications with various backends
           return [ 200, [ 'Content-Type' => 'text/plain' ], [ "Hello World" ] ],
       },
       client => sub {
-          my $cb = shift;
+          my $cb  = shift;
           my $req = HTTP::Request->new(GET => "http://localhost/hello");
           my $res = $cb->($req);
           like $res->content, qr/Hello World/;
@@ -47,7 +47,7 @@ Plack::Test - Test PSGI applications with various backends
    # positional params (app, client)
    my $app = sub { return [ 200, [], [ "Hello "] ] };
    test_psgi $app, sub {
-       my $cb = shift;
+       my $cb  = shift;
        my $res = $cb->(GET "/");
        is $res->content, "Hello";
    };
@@ -56,11 +56,10 @@ Plack::Test - Test PSGI applications with various backends
 =head1 DESCRIPTION
 
 Plack::Test is a unified interface to test PSGI applications using
-standard HTTP::Request and HTTP::Response objects. It also allows you
-to run PSGI applications in various ways, by default using C<MockHTTP>
-backend but can also use C<Server> backend, which uses one of
-L<Plack::Handler> implementations to run the web server to do live HTTP
-requests.
+L<HTTP::Request> and L<HTTP::Response> objects. It also allows you to run PSGI
+applications in various ways. The default backend is C<Plack::Test::MockHTTP>,
+but you may also use any L<Plack::Handler> implementation to run live HTTP
+requests against at web server
 
 =head1 FUNCTIONS
 
@@ -72,22 +71,25 @@ requests.
   test_psgi app => $app, client => $client;
 
 Runs the client test code C<$client> against a PSGI application
-C<$app>. The client callback gets one argument C<$cb>, that is a
-callback that accepts an HTTP::Request object and returns an
-HTTP::Response object.
+C<$app>. The client callback gets one argument C<$cb>, a
+callback that accepts an C<HTTP::Request> object and returns an
+C<HTTP::Response> object.
 
-For the convenience, HTTP::Request given to the callback is
-automatically adjusted to the correct protocol (I<http>) and host
-names (I<127.0.0.1> by default), so the following code just works.
+Use L<HTTP::Request::Common> to import shortcuts for creating requests for
+C<GET>, C<POST>, C<DELETE>, and C<PUT> operations.
+
+For your convenience, the C<HTTP::Request> given to the callback automatically
+uses the HTTP protocol and the localhost (I<127.0.0.1> by default), so the
+following code just works:
 
   use HTTP::Request::Common;
   test_psgi $app, sub {
-      my $cb = shift;
+      my $cb  = shift;
       my $res = $cb->(GET "/hello");
   };
 
 Note that however, it is not a good idea to pass an arbitrary
-(i.e. user-input) string to the C<GET> function or even C<<
+(i.e. user-input) string to C<GET> or even C<<
 HTTP::Request->new >> by assuming that it always represents a path,
 because:
 
@@ -101,7 +103,7 @@ might actually want.
 
 =head1 OPTIONS
 
-You can specify the L<Plack::Test> backend using the environment
+Specify the L<Plack::Test> backend using the environment
 variable C<PLACK_TEST_IMPL> or C<$Plack::Test::Impl> package variable.
 
 The available values for the backend are: