X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=lib%2FMooseX%2FRunnable.pm;h=5d0997fcad9d6eab4e120f84e9980ccebf1f986e;hb=d1de149811e3340e7847b387faf213827d9a2318;hp=e54bc8da44da2f8e4752c1893bb9579ba8ca43c7;hpb=00d7989a23f3ed99dcf5b3a58f0843cd9d47115a;p=gitmo%2FMooseX-Runnable.git

diff --git a/lib/MooseX/Runnable.pm b/lib/MooseX/Runnable.pm
index e54bc8d..5d0997f 100644
--- a/lib/MooseX/Runnable.pm
+++ b/lib/MooseX/Runnable.pm
@@ -1,4 +1,5 @@
 package MooseX::Runnable;
+# ABSTRACT: Tag a class as a runnable application
 use Moose::Role;
 
 requires 'run';
@@ -7,21 +8,20 @@ requires 'run';
 
 __END__
 
-=head1 NAME
-
-MooseX::Runnable - tag a class as a runnable application
+=pod
 
 =head1 SYNOPSIS
 
 Create a class, tag it runnable, and provide a C<run> method:
 
     package App::HelloWorld;
+    use feature 'say';
     use Moose;
 
     with 'MooseX::Runnable';
 
     sub run {
-       my $name = shift;
+       my ($self,$name) = @_;
        say "Hello, $name.";
        return 0; # success
     }
@@ -51,6 +51,13 @@ let's the computer abstract away some of the tedium this entails.
 
 =head1 REQUIRED METHODS
 
+=head2 run
+
+Your class must implement C<run>.  It accepts the commandline args
+(that were not consumed by another parser, if applicable) and returns
+an integer representing the UNIX exit value.  C<return 0> means
+success.
+
 =head1 THINGS YOU GET
 
 =head2 C<mx-run>
@@ -60,13 +67,38 @@ run it, using C<MooseX::Runnable::Run>.
 
 The syntax is:
 
-  mx-run <args for mx-run> Class::Name <args for Class::Name>
+  mx-run Class::Name
+
+  mx-run <args for mx-run> -- Class::Name <args for Class::Name>
 
 for example:
 
   mx-run -Ilib App::HelloWorld --args --go --here
 
+or:
+
+  mx-run -Ilib +Persistent --port 8080 -- App::HelloWorld --args --go --here
+
 =head2 C<MooseX::Runnable::Run>
 
 If you don't want to invoke your app with C<mx-run>, you can write a
 custom version using L<MooseX::Runnable::Run|MooseX::Runnable::Run>.
+
+=head1 ARCHITECTURE
+
+C<MX::Runnable> is designed to be extensible; users can run plugins
+from the command-line, and application developers can add roles to
+their class to control behavior.
+
+For example, if you consume L<MooseX::Getopt|MooseX::Getopt>, the
+command-line will be parsed with C<MooseX::Getopt>.  Any recognized
+args will be used to instantiate your class, and any extra args will
+be passed to C<run>.
+
+=head1 BUGS
+
+Many of the plugins shipped are unstable; they may go away, change,
+break, etc.  If there is no documentation for a plugin, it is probably
+just a prototype.
+
+=cut