Write more documentation.

dist.ini

@@ -4,16 +4,15 @@ author            = Rocco Caputo <rcaputo@cpan.org>
 license           = Perl_5
 copyright_holder  = Rocco Caputo
 
-[MetaResources]
-bugtracker        = http://rt.cpan.org/Public/Dist/Display.html?Name=Reflex
-repository        = http://github.com/rcaputo/reflex
-
 [Prereq]
 Scalar::Util      = 1.21
 POE               = 1.268
 Test::More        = 0.94
 Moose             = 0.92
 
+[Repository]
+git_remote = gh
+
 [ReadmeFromPod]
 [ReadmeMarkdownFromPod]
 [AllFiles]
@@ -30,6 +29,9 @@ Moose             = 0.92
 [MakeMaker]
 [ChangelogFromGit]
 
+; Not ready, unfortunately.
+;[CreditsFromGit]
+
 ; Goes last to pick up generated files.
 [Manifest]
 

eg/EchoStream.pm

@@ -10,12 +10,12 @@ sub on_stream_data {
 sub on_stream_failure {
 	my ($self, $args) = @_;
 	warn "$args->{errfun} error $args->{errnum}: $args->{errstr}\n";
-	$self->emit( event => "shutdown", args => {} );
+	$self->emit( event => "stopped", args => {} );
 }
 
 sub on_stream_closed {
 	my ($self, $args) = @_;
-	$self->emit( event => "shutdown", args => {} );
+	$self->emit( event => "stopped", args => {} );
 }
 
 sub DEMOLISH {

lib/Reflex/Callback/CodeRef.pm

@@ -24,7 +24,7 @@ Reflex::Callback::CodeRef - Callback adapter for plain code references
 
 =head1 SYNOPSIS
 
-In practice:
+Used within Reflex:
 
 	use Reflex::Callbacks qw(cb_coderef);
 
@@ -38,7 +38,7 @@ In practice:
 
 	$ct->run_all();
 
-Specifically:
+Low-level usage:
 
 	sub callback {
 		my $arg = shift;

lib/Reflex/Callback/Method.pm

@@ -25,7 +25,7 @@ Reflex::Callback::Method - Callback adapter for class and object methods
 
 =head1 SYNOPSIS
 
-In practice:
+Used within Reflex:
 
 	package MethodHandler;
 	use Moose;
@@ -55,7 +55,7 @@ In practice:
 
 	MethodHandler->new()->run_all();
 
-Specifically:
+Low-level usage:
 
 	{
 		package Object;

lib/Reflex/Callback/Promise.pm

@@ -36,7 +36,7 @@ Reflex::Callback::Promise - Condvar-like non-callback adapter
 
 =head1 SYNOPSIS
 
-In practice:
+Used within Reflex:
 
 	use Reflex::Timer;
 	use ExampleHelpers qw(eg_say);
@@ -50,7 +50,7 @@ In practice:
 		eg_say("promise timer returned an event (@$event)");
 	}
 
-Specifically:
+Low-level usage:
 
 	use Reflex::Callback::Promise;
 

lib/Reflex/Collection.pm

@@ -15,7 +15,7 @@ has objects => (
 
 sub remember {
 	my ($self, $object) = @_;
-	$self->observe($object, shutdown => cb_method($self, "cb_forget"));
+	$self->observe($object, stopped => cb_method($self, "cb_forget"));
 	$self->objects()->{$object} = $object;
 }
 
@@ -30,4 +30,88 @@ sub cb_forget {
 }
 
 1;
-# TODO - Document.
+
+__END__
+
+=head1 NAME
+
+Reflex::Collection - Autmatically manage a collection of Reflex objects
+
+=head1 SYNOPSIS
+
+	package TcpEchoServer;
+
+	use Moose;
+	extends 'Reflex::Listener';
+	use Reflex::Collection;
+	use EchoStream;
+
+	has clients => (
+		is      => 'rw',
+		isa     => 'Reflex::Collection',
+		default => sub { Reflex::Collection->new() },
+		handles => { remember_client => "remember" },
+	);
+
+	sub on_listener_accepted {
+		my ($self, $args) = @_;
+		$self->remember_client(
+			EchoStream->new(
+				handle => $args->{socket},
+				rd     => 1,
+			)
+		);
+	}
+
+	1;
+
+=head1 DESCRIPTION
+
+Some object manage collections of other objects.  For example, network
+servers must track objects that represent client connections.  If not,
+those objects would go out of scope, destruct, and disconnect their
+clients.
+
+Reflex::Collection is a generic object collection manager.  It exposes
+remember() and forget(), which may be mapped to other methods using
+Moose's "handles" aspect.
+
+Reflex::Collection goes beyond this simple hash-like interface.  It
+will automatically forget() objects that emit "stopped" events,
+triggering their destruction if nothing else refers to them.  This
+eliminates a large amount of repetitive work.
+
+=head2 new
+
+Create a new Reflex::Collection.  It takes no parameters.
+
+=head2 remember
+
+Remember an object.  Reflex::Collection works best if it contains the
+only references to the objects it manages, so you may often see
+objects remembered while they're constructed.  See the SYNOPSIS for
+one such example.
+
+remember() takes one parameter: the object to remember.
+
+=head2 forget
+
+Forget an object, returning its reference.  You've supplied the
+reference, so the returned one is usually redundant.  forget() takes
+one parameter: the object to forget.
+
+=head1 SEE ALSO
+
+L<Reflex>
+
+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/Timer.pm

@@ -72,73 +72,72 @@ sub stop {
 }
 
 1;
-# TODO - Document.
 
 __END__
 
 =head1 NAME
 
-Reflex::Timer - Observe the passage of time.
+Reflex::Timer - An object that observes the passage of time.
 
 =head1 SYNOPSIS
 
-# Not a complete program.  Many of the examples use Reflex::Timer.
-# You can't throw a stone without hitting one.
+	# Several examples in the eg directory use Reflex::Timer.
 
-	sub object_method {
-		my ($self, $args) = @_;
+	use warnings;
+	use strict;
 
-		$self->timer(
-			Reflex::Timer->new(
-				interval => 1,
-				auto_repeat => 1,
-			)
-		);
-	);
+	use lib qw(../lib);
 
-=head1 DESCRIPTION
+	use Reflex::Timer;
 
-Reflex::Timer emits events to mark the passage of time.
+	my $t = Reflex::Timer->new(
+		interval    => 1,
+		auto_repeat => 1,
+	);
 
-Its constructor takes a hash as an argument. 
-The interval specifies the interval between events are fired.
-auto_repeat is either specified as 1 or not specified and in the former
-case, the events will be fired repeatedly and in the latter, only one event
-is fired.
-event_name is a key in the hash that specifies what the event emitted should 
-be called. 
-TODO - Complete the API.  It's currently very incomplete.  It only
-handles relative delays via its "interval" constructor parameter, and
-automatic repeat via "auto_repeat".
+	while (my $event = $t->wait()) {
+		print "wait() returned an event (@$event)\n";
+	}
 
-TODO - Complete the documentation.
+=head1 DESCRIPTION
 
-=head1 GETTING HELP
+Reflex::Timer emits events to mark the passage of time.  Its interface
+is new and small.  Please contact the Reflex project if you need other
+features, or send us a pull request at github or gitorious.
 
-L<Reflex/GETTING HELP>
+=head1 PUBLIC ATTRIBUTES
 
-=head1 ACKNOWLEDGEMENTS
+=head2 interval
 
-L<Reflex/ACKNOWLEDGEMENTS>
+Define the interval between creation and the "tick" event's firing.
+If auto_repeat is also set, this becomes the interval between
+recurring "tick" events.
 
-=head1 SEE ALSO
+=head2 auto_repeat
 
-L<Reflex> and L<Reflex/SEE ALSO>
+A Boolean value.  When true, Reflex::Timer will repeatedly fire "tick"
+events every interval seconds.
 
-=head1 BUGS
+=head1 PUBLIC EVENTS
 
-L<Reflex/BUGS>
+=head2 tick
 
-=head1 CORE AUTHORS
+Reflex::Timer emits "tick" events.  We're looking for a better name,
+so this may change in the future.  Your suggestions can help solidify
+the interface quicker.
 
-L<Reflex/CORE AUTHORS>
-
-=head1 OTHER CONTRIBUTORS
-
-L<Reflex/OTHER CONTRIBUTORS>
+=head1 SEE ALSO
 
-=head1 COPYRIGHT AND LICENSE
+L<Reflex>
 
-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