mention which methods are meant to be overloaded in subclasses

mojolicious · Mar 24, 2012 · 5dadc53 · 5dadc53
1 parent 0a90fc0
commit 5dadc53
Show file tree

Hide file tree

Showing 10 changed files with 44 additions and 32 deletions.
diff --git a/Changes b/Changes
@@ -1,5 +1,8 @@
 This file documents the revision history for Perl extension Mojolicious.
 
+2.68  2012-03-25
+  - Improved documentation.
+
 2.67  2012-03-24
   - Added start_app method to Mojo::Command.
   - Improved documentation.

diff --git a/lib/Mojo.pm b/lib/Mojo.pm
@@ -173,8 +173,9 @@ Application configuration.
   $app->handler($tx);
 
 The handler is the main entry point to your application or framework and
-will be called for each new transaction, which will usually be a
-L<Mojo::Transaction::HTTP> or L<Mojo::Transaction::WebSocket> object.
+meant to be overloaded in a subclass. It will be called for each new
+transaction, which will usually be a L<Mojo::Transaction::HTTP> or
+L<Mojo::Transaction::WebSocket> object.
 
   sub handler {
     my ($self, $tx) = @_;

diff --git a/lib/Mojo/Asset.pm b/lib/Mojo/Asset.pm
@@ -59,19 +59,21 @@ the following new ones.
 
   $asset = $asset->add_chunk('foo bar baz');
 
-Add chunk of data to asset.
+Add chunk of data to asset, meant to be overloaded in a subclass.
 
 =head2 C<contains>
 
   my $position = $asset->contains('bar');
 
-Check if asset contains a specific string.
+Check if asset contains a specific string, meant to be overloaded in a
+subclass.
 
 =head2 C<get_chunk>
 
   my $chunk = $asset->get_chunk($offset);
 
-Get chunk of data starting from a specific position.
+Get chunk of data starting from a specific position, meant to be overloaded
+in a subclass.
 
 =head2 C<is_file>
 
@@ -83,19 +85,19 @@ False.
 
   $asset = $asset->move_to('/foo/bar/baz.txt');
 
-Move asset data into a specific file.
+Move asset data into a specific file, meant to be overloaded in a subclass.
 
 =head2 C<size>
 
   my $size = $asset->size;
 
-Size of asset data in bytes.
+Size of asset data in bytes, meant to be overloaded in a subclass.
 
 =head2 C<slurp>
 
   my $string = $asset->slurp;
 
-Read all asset data at once.
+Read all asset data at once, meant to be overloaded in a subclass.
 
 =head1 SEE ALSO
 

diff --git a/lib/Mojo/Command.pm b/lib/Mojo/Command.pm
@@ -102,8 +102,7 @@ sub get_data {
 # "You don’t like your job, you don’t strike.
 #  You go in every day and do it really half-assed. That’s the American way."
 sub help {
-  my $self = shift;
-  print $self->usage;
+  print shift->usage;
   exit 0;
 }
 
@@ -209,6 +208,9 @@ L<Mojo::Command> implements the following attributes.
 
 Currently active application, defaults to a L<Mojo::HelloWorld> object.
 
+  # Introspect
+  say "Template path: $_" for @{$command->app->renderer->paths};
+
 =head2 C<description>
 
   my $description = $command->description;
@@ -334,7 +336,7 @@ relative file.
   $command->run;
   $command->run(@ARGV);
 
-Run command.
+Run command, meant to be overloaded in a subclass.
 
 =head2 C<write_file>
 

diff --git a/lib/Mojo/Content.pm b/lib/Mojo/Content.pm
@@ -494,13 +494,14 @@ implements the following new ones.
 
   my $success = $content->body_contains('foo bar baz');
 
-Check if content contains a specific string.
+Check if content contains a specific string, meant to be overloaded in a
+subclass.
 
 =head2 C<body_size>
 
   my $size = $content->body_size;
 
-Content size in bytes.
+Content size in bytes, meant to be overloaded in a subclass.
 
 =head2 C<boundary>
 
@@ -542,7 +543,8 @@ Generate dynamic content.
 
   my $chunk = $content->get_body_chunk(0);
 
-Get a chunk of content starting from a specfic position.
+Get a chunk of content starting from a specfic position, meant to be
+overloaded in a subclass.
 
 =head2 C<get_header_chunk>
 

diff --git a/lib/Mojo/Cookie.pm b/lib/Mojo/Cookie.pm
@@ -117,13 +117,13 @@ following new ones.
 
   my $cookies = $cookie->parse($string);
 
-Parse cookies.
+Parse cookies, meant to be overloaded in a subclass.
 
 =head2 C<to_string>
 
   my $string = $cookie->to_string;
 
-Render cookie.
+Render cookie, meant to be overloaded in a subclass.
 
 =head1 SEE ALSO
 

diff --git a/lib/Mojo/Reactor.pm b/lib/Mojo/Reactor.pm
@@ -103,7 +103,7 @@ L<Mojo::Reactor::Poll>.
   $reactor = $reactor->io($handle => sub {...});
 
 Watch handle for I/O events, invoking the callback whenever handle becomes
-readable or writable.
+readable or writable, meant to be overloaded in a subclass.
 
   # Callback will be invoked twice if handle becomes readable and writable
   $reactor->io($handle => sub {
@@ -122,22 +122,22 @@ tainted sockets.
 
   my $success = $reactor->is_running;
 
-Check if reactor is running.
+Check if reactor is running, meant to be overloaded in a subclass.
 
 =head2 C<one_tick>
 
   $reactor->one_tick;
 
 Run reactor until at least one event has been handled or no events are being
-watched anymore. Note that this method can recurse back into the reactor, so
-you need to be careful.
+watched anymore, meant to be overloaded in a subclass. Note that this method
+can recurse back into the reactor, so you need to be careful.
 
 =head2 C<recurring>
 
   my $id = $reactor->recurring(0.25 => sub {...});
 
 Create a new recurring timer, invoking the callback repeatedly after a given
-amount of time in seconds.
+amount of time in seconds, meant to be overloaded in a subclass.
 
   # Invoke as soon as possible
   $reactor->recurring(0 => sub { say 'Reactor tick.' });
@@ -147,27 +147,28 @@ amount of time in seconds.
   my $success = $reactor->remove($handle);
   my $success = $reactor->remove($id);
 
-Remove handle or timer.
+Remove handle or timer, meant to be overloaded in a subclass.
 
 =head2 C<start>
 
   $reactor->start;
 
 Start watching for I/O and timer events, this will block until C<stop> is
-called or no events are being watched anymore.
+called or no events are being watched anymore, meant to be overloaded in a
+subclass.
 
 =head2 C<stop>
 
   $reactor->stop;
 
-Stop watching for I/O and timer events.
+Stop watching for I/O and timer events, meant to be overloaded in a subclass.
 
 =head2 C<timer>
 
   my $id = $reactor->timer(0.5 => sub {...});
 
 Create a new timer, invoking the callback after a given amount of time in
-seconds.
+seconds, meant to be overloaded in a subclass.
 
   # Invoke as soon as possible
   $reactor->timer(0 => sub { say 'Next tick.' });
@@ -176,7 +177,8 @@ seconds.
 
   $reactor = $reactor->watch($handle, $readable, $writable);
 
-Change I/O events to watch handle for with C<true> and C<false> values.
+Change I/O events to watch handle for with C<true> and C<false> values, meant
+to be overloaded in a subclass.
 
   # Watch only for readable events
   $reactor->watch($handle, 1, 0);

diff --git a/lib/Mojo/Server.pm b/lib/Mojo/Server.pm
@@ -157,7 +157,7 @@ Load application from script.
 
   $server->run;
 
-Run server.
+Run server, meant to be overloaded in a subclass.
 
 =head1 SEE ALSO
 

diff --git a/lib/Mojo/Transaction.pm b/lib/Mojo/Transaction.pm
@@ -196,13 +196,13 @@ Transaction closed.
 
   $tx->client_read($chunk);
 
-Read and process client data.
+Read and process client data, meant to be overloaded in a subclass.
 
 =head2 C<client_write>
 
   my $chunk = $tx->client_write;
 
-Write client data.
+Write client data, meant to be overloaded in a subclass.
 
 =head2 C<connection>
 
@@ -252,13 +252,13 @@ Transaction closed.
 
   $tx->server_read($chunk);
 
-Read and process server data.
+Read and process server data, meant to be overloaded in a subclass.
 
 =head2 C<server_write>
 
   my $chunk = $tx->server_write;
 
-Write server data.
+Write server data, meant to be overloaded in a subclass.
 
 =head2 C<success>
 

diff --git a/lib/Mojolicious.pm b/lib/Mojolicious.pm
@@ -33,7 +33,7 @@ has static   => sub { Mojolicious::Static->new };
 has types    => sub { Mojolicious::Types->new };
 
 our $CODENAME = 'Leaf Fluttering In Wind';
-our $VERSION  = '2.67';
+our $VERSION  = '2.68';
 
 # "These old doomsday devices are dangerously unstable.
 #  I'll rest easier not knowing where they are."