more docs

3 files changed, 31 insertions, 0 deletions

diff --git a/lib/Web/Request.pm b/lib/Web/Request.pm
index 84174f4..905d1d7 100644
--- a/lib/Web/Request.pm
+++ b/lib/Web/Request.pm
@@ -22,6 +22,23 @@ use URI::Escape ();
 
 =head1 DESCRIPTION
 
+Web::Request is a request class for L<PSGI> applications. It provides access to
+all of the information received in a request, generated from the PSGI
+environment. The available methods are listed below.
+
+Note that Web::Request objects are intended to be (almost) entirely read-only -
+although some methods (C<headers>, C<uri>, etc) may return mutable objects,
+changing those objects will have no effect on the actual environment, or the
+return values of any of the other methods. Doing this is entirely unsupported.
+In addition, the return values of most methods that aren't direct accesses to
+C<env> are cached, so if you do modify the actual environment hashref, you
+should create a new Web::Request object for it.
+
+The one exception is the C<encoding> attribute, which is allowed to be
+modified. Changing the encoding will change the return value of any subsequent
+calls to C<content>, C<query_parameters>, C<all_query_parameters>,
+C<body_parameters>, and C<all_body_parameters>.
+
 =cut
 
 has env => (
diff --git a/lib/Web/Request/Upload.pm b/lib/Web/Request/Upload.pm
index 674ab8d..b454aec 100644
--- a/lib/Web/Request/Upload.pm
+++ b/lib/Web/Request/Upload.pm
@@ -18,6 +18,11 @@ use Web::Request::Types;
 
 =head1 DESCRIPTION
 
+This class represents a single uploaded file, generally from an C<< <input
+type="file" /> >> element. You most likely don't want to create instances of
+this class yourself; they will be created for you via the C<uploads> method on
+L<Web::Request>.
+
 =cut
 
 has headers => (
diff --git a/lib/Web/Response.pm b/lib/Web/Response.pm
index 5ee5387..bc82526 100644
--- a/lib/Web/Response.pm
+++ b/lib/Web/Response.pm
@@ -21,6 +21,15 @@ use Web::Request::Types ();
 
 =head1 DESCRIPTION
 
+Web::Response is a response class for L<PSGI> applications. Generally, you will
+want to create instances of this class via C<new_response> on the request
+object, since that allows a framework which subclasses L<Web::Request> to also
+return an appropriate subclass of Web::Response.
+
+All attributes on Web::Response objects are writable, and the final state of
+them will be used to generate a real L<PSGI> response when C<finalize> is
+called.
+
 =cut
 
 has status => (