--- AnyEvent-MP/MP.pm	2009/09/04 21:52:09	1.79
+++ AnyEvent-MP/MP.pm	2009/09/08 01:42:14	1.84
@@ -85,7 +85,7 @@
 (no listening ports). Private nodes cannot talk to other private nodes
 currently.
 
-=item node ID - C<[a-za-Z0-9_\-.:]+>
+=item node ID - C<[A-Z_][a-zA-Z0-9_\-.:]*>
 
 A node ID is a string that uniquely identifies the node within a
 network. Depending on the configuration used, node IDs can look like a
@@ -99,20 +99,32 @@
 endpoints - binds. Currently, only standard C<ip:port> specifications can
 be used, which specify TCP ports to listen on.
 
-=item seeds - C<host:port>
+=item seed nodes
 
 When a node starts, it knows nothing about the network. To teach the node
 about the network it first has to contact some other node within the
 network. This node is called a seed.
 
-Seeds are transport endpoint(s) of as many nodes as one wants. Those nodes
-are expected to be long-running, and at least one of those should always
-be available. When nodes run out of connections (e.g. due to a network
-error), they try to re-establish connections to some seednodes again to
-join the network.
+Apart from the fact that other nodes know them as seed nodes and they have
+to have fixed listening addresses, seed nodes are perfectly normal nodes -
+any node can function as a seed node for others.
+
+In addition to discovering the network, seed nodes are also used to
+maintain the network and to connect nodes that otherwise would have
+trouble connecting. They form the backbone of the AnyEvent::MP network.
+
+Seed nodes are expected to be long-running, and at least one seed node
+should always be available.
+
+=item seeds - C<host:port>
 
-Apart from being sued for seeding, seednodes are not special in any way -
-every public node can be a seednode.
+Seeds are transport endpoint(s) (usually a hostname/IP address and a
+TCP port) of nodes thta should be used as seed nodes.
+
+The nodes listening on those endpoints are expected to be long-running,
+and at least one of those should always be available. When nodes run out
+of connections (e.g. due to a network error), they try to re-establish
+connections to some seednodes again to join the network.
 
 =back
 
@@ -623,13 +635,19 @@
 exists or it runs out of package names.
 
 The init function is then called with the newly-created port as context
-object (C<$SELF>) and the C<@initdata> values as arguments.
+object (C<$SELF>) and the C<@initdata> values as arguments. It I<must>
+call one of the C<rcv> functions to set callbacks on C<$SELF>, otherwise
+the port might not get created.
 
 A common idiom is to pass a local port, immediately monitor the spawned
 port, and in the remote init function, immediately monitor the passed
 local port. This two-way monitoring ensures that both ports get cleaned up
 when there is a problem.
 
+C<spawn> guarantees that the C<$initfunc> has no visible effects on the
+caller before C<spawn> returns (by delaying invocation when spawn is
+called for the local node).
+
 Example: spawn a chat server port on C<$othernode>.
 
    # this node, executed from within a port context:
@@ -653,6 +671,7 @@
    my $port = shift;
    my $init = shift;
 
+   # rcv will create the actual port
    local $SELF = "$NODE#$port";
    eval {
       &{ load_func $init }
@@ -858,6 +877,9 @@
 L<AnyEvent::MP::Global> - network maintainance and port groups, to find
 your applications.
 
+L<AnyEvent::MP::LogCatcher> - simple service to display log messages from
+all nodes.
+
 L<AnyEvent>.
 
 =head1 AUTHOR