Add preliminary documentation to the last three modules.

lib/Reflex/POE/Postback.pm

@@ -52,7 +52,6 @@ sub DESTROY {
 }
 
 1;
-# TODO - Document.
 
 __END__
 
@@ -62,51 +61,100 @@ Reflex::POE::Postback - Communicate with POE components expecting postbacks.
 
 =head1 SYNOPSIS
 
-# Not a complete example.  Please see eg-11-poco-postback.pl in the
-# examples for a working one.
+Not a complete example.  Please see eg-11-poco-postback.pl in the eg
+directory for a complete working program.
 
-	$self->component->request(
-		Reflex::POE::Postback->new(
-			$self, "on_component_result", { cookie => 123 }
-		),
+	my $postback = Reflex::POE::Postback->new(
+		$self, "on_component_result", { cookie => 123 }
 	);
 
-TODO - Needs a better example.
-
 =head1 DESCRIPTION
 
-Reflex::POE::Postback creates an object that's compatible with the POE
-postback.  These may be given to POE components that require postbacks to
-work.
+Reflex::POE::Postback creates an object that's substitutes for
+POE::Session postbacks.  When invoked, however, they sent events back
+to the object and method (and with optional continuation data)
+provided during construction.
 
-TODO - Complete the documentation.
+Reflex::POE::Postback was designed to interact with POE modules that
+want to respond via caller-provided postbacks.  Authors are encouraged
+to encapsulate POE interaction within Reflex objects.  Most users
+should therefore not need use Reflex::POE::Postback (or other
+Reflex::POE helpers) directly.
 
-=head1 GETTING HELP
+=head2 Public Methods
 
-L<Reflex/GETTING HELP>
+=head3 new
 
-=head1 ACKNOWLEDGEMENTS
+new() constructs a new Reflex::POE::Postback object, which will be a
+blessed coderef following POE's postback convention.
 
-L<Reflex/ACKNOWLEDGEMENTS>
+It takes three positional parameters: the required object and method
+to invoke when the postback is called, and an optional context that
+will be passed verbatim to the callback.
 
-=head1 SEE ALSO
+=head2 Callback Parameters
 
-L<Reflex> and L<Reflex/SEE ALSO>
+=head3 context
 
-=head1 BUGS
+The "context" callback parameter contains whatever was supplied to the
+Reflex::POE::Postback when it was created.  In the case of the
+SYNOPSIS, that would be:
 
-L<Reflex/BUGS>
+	sub on_component_result {
+		my ($self, $arg) = @_;
+
+		# Displays: 123
+		print $arg->{context}{cookie}, "\n";
+	}
+
+=head3 response
+
+"response" contains an array reference that holds whatever was passed
+to the postback.  If we assume this postback call:
+
+	$postback->(qw(eight six seven five three oh nine));
+
+Then the callback might look something like this:
 
-=head1 CORE AUTHORS
+	sub on_component_result {
+		my ($self, $arg) = @_;
 
-L<Reflex/CORE AUTHORS>
+		# Displays: nine
+		print "$arg->{response}[-1]\n";
+	}
 
-=head1 OTHER CONTRIBUTORS
+=head1 CAVEATS
 
-L<Reflex/OTHER CONTRIBUTORS>
+Reflex::POE::Postback must produce objects as blessed coderefs.  This
+is something I don't know how to do yet with Moose, so Moose isn't
+used.  Therefore, Reflex::POE::Postback doesn't do a lot of things one
+might expect after working with other Reflex objects.
 
-=head1 COPYRIGHT AND LICENSE
+If Moose can be used later, it may fundamentally change the entire
+interface.  The goal is to do this only once, however.
 
-L<Reflex/COPYRIGHT AND LICENSE>
+It might be nice to map positional response parameters to named
+parameters.  Reflex::POE::Wheel does this, but it remains to be seen
+whether that's considered cumbersome.
+
+=head1 SEE ALSO
+
+L<Moose::Manual::Concepts>
+
+L<Reflex>
+L<Reflex::POE::Event>
+L<Reflex::POE::Session>
+L<Reflex::POE::Wheel::Run>
+L<Reflex::POE::Wheel>
+
+L<Reflex/ACKNOWLEDGEMENTS>
+L<Reflex/ASSISTANCE>
+L<Reflex/AUTHORS>
+L<Reflex/BUGS>
+L<Reflex/BUGS>
+L<Reflex/CONTRIBUTORS>
+L<Reflex/COPYRIGHT>
+L<Reflex/LICENSE>
+L<Reflex/TODO>
 
 =cut

lib/Reflex/POE/Wheel.pm

@@ -5,7 +5,7 @@ use Scalar::Util qw(weaken);
 use POE::Wheel;
 
 has wheel => (
-	isa     => 'Object|Undef',
+	isa     => 'Maybe[POE::Wheel]',
 	is      => 'rw',
 );
 
@@ -88,7 +88,6 @@ sub _deliver {
 }
 
 1;
-# TODO - Document.
 
 __END__
 
@@ -98,60 +97,184 @@ Reflex::POE::Wheel - Base class for POE::Wheel wrappers.
 
 =head1 SYNOPSIS
 
-# Not a complete example.  Consider looking at the source for
-# Reflex::POE::Wheel::Run, which subclasses Reflex::POE::Wheel.
-
-TODO - Need an example.
+There is no concise synopsis at this time.  Setting up a new
+Reflex::POE::Wheel is rather involved.  The source for
+L<Reflex::POE::Wheel::Run> may serve as an example.
 
 =head1 DESCRIPTION
 
-Reflex::POE::Wheel is a base class for POE::Wheel wrappers.
-Subclasses will configure Reflex::POE::Wheel to provide the proper
-POE::Wheel constructor parameters.  Additional configuration converts
-the POE::Wheel events into Reflex::Object events.
+Reflex::POE::Wheel is a base class for Reflex objects that wrap and
+observe POE::Wheel objects.  Subclasses define a handful of methods
+that describe the wheels they wrap.  Reflex::POE::Wheel will use the
+configuration to validate constructor parameters, map wheel events to
+Reflex events, and map positional callback parameters to named ones.
 
-Methods are not yet converted automatically.  It seems more sensible
-to provide a native Reflex::Object interface, although one could
-certainly use Moose's "handles" attribute option to pass the wheel's
-methods through the wrapper.
+It's rather handy once you get used to it.
+
+=head2 Public Attributes
+
+=head3 wheel
+
+Currently Reflex::POE::Wheel exposes the raw POE::Wheel via its
+wheel() attribute.  This will be undefined if the wheel hasn't been
+set up yet.
 
-TODO - Complete the documentation.
+=head2 Public Methods
 
-=head2 wheel_id
+=head3 wheel_id
 
-Return the internal wheel's ID.
+The wheel_id() method returns the ID of the POE::Wheel being managed.
+C<< $foo->wheel()->ID() >> can also be used instead.
 
-=head2 demolish_wheel
+=head3 demolish_wheel
 
 Cause the internal wheel to be demolished.  Provided as a method since
 some wheels may require special handling.
 
-=head1 GETTING HELP
+=head2 Required Subclass Methods
 
-L<Reflex/GETTING HELP>
+These subclass methods are used to configure subclasses for their
+chosen POE::Wheel objects.
 
-=head1 ACKNOWLEDGEMENTS
+=head3 event_to_index
 
-L<Reflex/ACKNOWLEDGEMENTS>
+event_to_index() maps POE::Wheel events to consecutive integer event
+IDs.  event_emit_names() will provide Reflex-friendly event names
+based on the event IDs.  event_param_names() will provide parameter
+names that correspond to the wheel's positional parameters.
 
-=head1 SEE ALSO
+This mapping is from Reflex::POE::Wheel::Run.  It will make more sense
+in the context of event_emit_names() and event_param_names().
 
-L<Reflex> and L<Reflex/SEE ALSO>
+	sub event_to_index {
+		return(
+			{
+				StdinEvent  => 0,
+				StdoutEvent => 1,
+				StderrEvent => 2,
+				ErrorEvent  => 3,
+				CloseEvent  => 4,
+			},
+		);
+	}
 
-=head1 BUGS
+=head3 event_emit_names
+
+event_emit_names() returns an array reference that maps
+Reflex::POE::Wheel's event IDs to Reflex-friendly event names.
+
+Here's an example from Reflex::POE::Wheel::Run.  The wheel's
+StdinEvent (ID 0) is emitted as "stdin" (the 0th element in
+event_emit_names()).  StdoutEvent becomes "stdout", and so on.
+
+	sub event_emit_names {
+		return(
+			[
+				'stdin',  # StdinEvent
+				'stdout', # StdoutEvent
+				'stderr', # StderrEvent
+				'error',  # ErrorEvent
+				'closed', # ClosedEvent
+			],
+		);
+	}
 
-L<Reflex/BUGS>
+=head3 event_param_names
+
+event_param_names() returns an array reference that maps
+Reflex::POE::Wheel's event IDs to Reflex-friendly lists of parameter
+names.  The underlying POE::Wheel's positional parameters will be
+mapped to these names before the Reflex object emits them.
+
+Here's yet another example from Reflex::POE::Wheel::Run.  StdinEvent
+and StdoutEvent each return two parameters.  The Reflex object will
+emit their ARG0 as the named parameter "output", and ARG1 becomes the
+named parameter "wheel_id".
+
+	sub event_param_names {
+		return(
+			[
+				[ "wheel_id" ],
+				[ "output", "wheel_id" ],
+				[ "output", "wheel_id" ],
+				[ "operation", "errnum", "errstr", "wheel_id", "handle_name" ],
+				[ "wheel_id" ],
+			]
+		);
+	}
+
+=head3 wheel_class
+
+wheel_class() returns a simple string---the class name of the wheel to
+construct.
+
+=head3 valid_params
+
+The valid_params() method returns a hash reference keyed on valid
+constructor parameters.  Values don't matter at this time.
+Reflex::POE::Wheel uses this hash reference to pre-validate
+construction of underlying POE::Wheel objects.
+
+POE::Wheel::Run takes quite a lot of parameters, most of which are
+optional.
+
+	sub valid_params {
+		return(
+			{
+				CloseOnCall => 1,
+				Conduit => 1,
+				Filter => 1,
+				Group => 1,
+				NoSetPgrp => 1,
+				NoSetSid => 1,
+				Priority => 1,
+				Program => 1,
+				ProgramArgs => 1,
+				StderrDriver => 1,
+				StderrFilter => 1,
+				StdinDriver => 1,
+				StdinFilter => 1,
+				StdioDriver => 1,
+				StdioFilter => 1,
+				StdoutDriver => 1,
+				StdoutFilter => 1,
+				User => 1,
+			}
+		);
+	}
+
+=head1 CAVEATS
+
+The demolish() name is heading towards deprecation in favor of
+something shorter and more widely recognized, perhaps stop().  The
+jury is still out, however.
 
-=head1 CORE AUTHORS
+Methods are not yet converted automatically.  It seems more sensible
+to provide a native Reflex::Object interface.  On the other hand, it
+may be possible for Moose's "handles" attribute option to pass the
+wheel's methods through the wrapper.  More investigation is required.
 
-L<Reflex/CORE AUTHORS>
+wheel() or wheel_id() will be deprecated, depending upon which is
+considered redundant.
 
-=head1 OTHER CONTRIBUTORS
+=head1 SEE ALSO
 
-L<Reflex/OTHER CONTRIBUTORS>
+L<Moose::Manual::Concepts>
 
-=head1 COPYRIGHT AND LICENSE
+L<Reflex>
+L<Reflex::POE::Event>
+L<Reflex::POE::Postback>
+L<Reflex::POE::Session>
+L<Reflex::POE::Wheel::Run>
 
-L<Reflex/COPYRIGHT AND LICENSE>
+L<Reflex/ACKNOWLEDGEMENTS>
+L<Reflex/ASSISTANCE>
+L<Reflex/AUTHORS>
+L<Reflex/BUGS>
+L<Reflex/BUGS>
+L<Reflex/CONTRIBUTORS>
+L<Reflex/COPYRIGHT>
+L<Reflex/LICENSE>
+L<Reflex/TODO>
 
 =cut