Documentation improvements

Author: bbrtj

Changes

@@ -3,6 +3,7 @@ Revision history for Kelp
 {{$NEXT}}
             [Changes]
             - Fixed psgi routes not working with custom controllers
+            - Documentation improvements
 
 2.16 - 2024-07-05
             [New Interface]

lib/Kelp/Context.pm

@@ -131,16 +131,20 @@ Returns a controller of a given name. The name will be mangled according to the
 base route class of the application. Contains extra checks to ensure the input
 is valid and loads the controller class if it wasn't loaded yet.
 
-If the controller name is undef, the base controller is returned.
+If the controller name is C<undef>, the base controller is returned.
 
 =head2 set_controller
 
-Like L</controller>, but does not have any special checks for correctness and
-only accepts a full class name. It also modifies the L</current> to the
-controller after constructing it. It's optimized for speed and used only
-internally.
+Similar to L</controller>, but does not have any special checks for correctness
+and only accepts a full class name. It also modifies the L</current> to the
+controller after constructing it. Passing a false value will result in
+reverting the current context back to the app object.
+
+It's optimized for speed and only used internally, so it's not recommended to
+use it unless you extend Kelp router itself.
 
 =head2 clear
 
-Clears context in anticipation of the next request.
+Clears context in anticipation of the next request. Called automatically at the
+start of every request.
 

lib/Kelp/Manual/Controllers.pod

@@ -16,14 +16,15 @@ class.
 
 Controllers lets you separate some of the route handling logic to other classes
 and have your subs take the object of the correct class as the first argument.
-In Kelp, there is no special base class for controllers - all controllers must
-be subclasses of L<Kelp>.
+In Kelp, there is no special base class for controllers by default - all
+controllers must be subclasses of L<Kelp>, unless you want to develop your own
+base controller - see L</Use different method than reblessing>.
 
 =head2 Reblessing details
 
 Reblessing will happen after request is matched to a route. Route handler has
 to be specified as class and method string, and class must be a subclass of class
-configured for L<Kelp::Routes/base>. L<Kelp::Routes/rebless> must albo be
+configured for L<Kelp::Routes/base>. L<Kelp::Routes/rebless> must also be
 enabled for that to occur.
 
 The default value of C<base> field is the application class, so your
@@ -206,8 +207,8 @@ default C<context_obj>, which is the class name of the context:
 
 =head1 CAVEATS
 
-There are some controller gotchas which come from a fact that they are not
-constructed like a regular object:
+There are some controller gotchas which come from a fact that they are not by
+default constructed like a regular object:
 
 =head2 Main application object is shallow-cloned before rebless
 
@@ -233,12 +234,12 @@ long as you don't instantiate your controllers before app building is finished.
 
 Controllers are never actually constructed, but instead the main app object is
 cloned and reblessed into the correct class. Don't expect your override of
-C<new> or C<build> to work.
+C<new> or C<build> to ever be called. No automatic controller initialization
+happens in Kelp.
 
-No automatic controller initialization happens in Kelp. If you'd like to access
-a controller in other context than route handling - for example in C<build>
-method, allowing you to move route definitions to the controller - you may use
-C<context> tracking object:
+If you'd like to access a controller in other context than route handling - for
+example in C<build> method, allowing you to move route definitions to the
+controller - you may use C<context> tracking object:
 
     # in MyApp.pm
     sub build {

lib/Kelp/Manual/Cookbook.pod

@@ -89,18 +89,9 @@ A slightly shorter version with state variables and no ping:
 
     # Use $self->dbh from here on ...
 
-    sub some_route {
-        my $self = shift;
-
-        $self->dbh->selectrow_array(q[
-            SELECT * FROM users
-            WHERE clue > 0
-        ]);
-    }
-
 Same methods can be used for accessing the schema of L<DBIx::Class>.
 
-=head2 Custom 404 and 500 error pages
+=head2 Custom error pages
 
 =head3 Error templates
 
@@ -112,49 +103,14 @@ C<< $self->res->render_error >>.
 
 =head3 Within the route
 
-You can set the response headers and content within the route:
+For one-off rendering of errors, you can alternatively set the response headers
+and content within the route:
 
     sub some_route {
         my $self = shift;
         $self->res->set_code(404)->template('my_404_template');
     }
 
-=head3 By overriding the Kelp::Response class
-
-To make custom 500, 404 and other error pages, you will have to subclass the
-L<Kelp::Response> module and override the I<render_404> and I<render_500> subroutines.
-Let's say your app's name is Foo and its class is in I<lib/Foo.pm>. Now create a
-file I<lib/Foo/Response.pm>:
-
-    package Foo::Response;
-    use Kelp::Base 'Kelp::Response';
-
-    sub render_404 {
-        my $self = shift;
-        $self->template('my_custom_404');
-    }
-
-    sub render_500 {
-        my $self = shift;
-        $self->template('my_custom_500');
-    }
-
-Then, in I<lib/Foo.pm>, you have to tell Kelp to use your custom response class
-like this:
-
-    sub response {
-        my $self = shift;
-        return Foo::Response->new( app => $self );
-    }
-
-Don't forget you need to create I<views/my_custom_404.tt> and
-I<views/my_custom_500.tt>. You can add other error rendering subroutines too, for
-example:
-
-    sub render_401 {
-        # Render your custom 401 error here
-    }
-
 =head2 Altering the behavior of a Kelp class method
 
 The easiest solution would be to use L<KelpX::Hooks> module available on CPAN:
@@ -228,9 +184,14 @@ use L<Plack::Middleware::ReverseProxy>.
 
 (REMOTE_ADDR is not set at all when using the proxy via filesocket).
 
-=head2 Changing the default access logging
+=head2 Changing the default logging
+
+Default log format can be modified by configuring the C<Logger> module. See
+L<Kelp::Module::Logger/date_format> and L<Kelp::Module::Logger/log_format>.
+Alternatively, L<Log::Dispatch> can be configured with its own callback to
+format the message to be logged.
 
-Access logs reported by Kelp through C<logger> can be modified or disabled by
+Access logs reported by Kelp through C<Logger> can be modified or disabled by
 writing your own customized L<Kelp/before_dispatch> method (not calling the
 parent version).