--- AnyEvent-MP/MP.pm	2009/08/04 22:13:45	1.27
+++ AnyEvent-MP/MP.pm	2009/08/04 23:16:57	1.29
@@ -45,31 +45,43 @@
 
 =item port
 
-A port is something you can send messages to with the C<snd> function, and
-you can register C<rcv> handlers with. All C<rcv> handlers will receive
-messages they match, messages will not be queued.
+A port is something you can send messages to (with the C<snd> function).
+
+Some ports allow you to register C<rcv> handlers that can match specific
+messages. All C<rcv> handlers will receive messages they match, messages
+will not be queued.
 
 =item port id - C<noderef#portname>
 
-A port id is always the noderef, a hash-mark (C<#>) as separator, followed
-by a port name (a printable string of unspecified format).
+A port id is normaly the concatenation of a noderef, a hash-mark (C<#>) as
+separator, and a port name (a printable string of unspecified format). An
+exception is the the node port, whose ID is identical to it's node
+reference.
 
 =item node
 
 A node is a single process containing at least one port - the node
-port. You can send messages to node ports to let them create new ports,
-among other things.
+port. You can send messages to node ports to find existing ports or to
+create new ports, among other things.
 
-Initially, nodes are either private (single-process only) or hidden
-(connected to a master node only). Only when they epxlicitly "become
-public" can you send them messages from unrelated other nodes.
+Nodes are either private (single-process only), slaves (connected to a
+master node only) or public nodes (connectable from unrelated nodes).
 
 =item noderef - C<host:port,host:port...>, C<id@noderef>, C<id>
 
-A noderef is a string that either uniquely identifies a given node (for
-private and hidden nodes), or contains a recipe on how to reach a given
+A node reference is a string that either simply identifies the node (for
+private and slave nodes), or contains a recipe on how to reach a given
 node (for public nodes).
 
+This recipe is simply a comma-separated list of C<address:port> pairs (for
+TCP/IP, other protocols might look different).
+
+Node references come in two flavours: resolved (containing only numerical
+addresses) or unresolved (where hostnames are used instead of addresses).
+
+Before using an unresolved node reference in a message you first have to
+resolve it.
+
 =back
 
 =head1 VARIABLES/FUNCTIONS
@@ -93,6 +105,7 @@
 our $VERSION = '0.1';
 our @EXPORT = qw(
    NODE $NODE *SELF node_of _any_
+   resolve_node
    become_slave become_public
    snd rcv mon kil reg psub
    port
@@ -117,6 +130,35 @@
 
 Extracts and returns the noderef from a portid or a noderef.
 
+=item $cv = resolve_node $noderef
+
+Takes an unresolved node reference that may contain hostnames and
+abbreviated IDs, resolves all of them and returns a resolved node
+reference.
+
+In addition to C<address:port> pairs allowed in resolved noderefs, the
+following forms are supported:
+
+=over 4
+
+=item the empty string
+
+An empty-string component gets resolved as if the default port (4040) was
+specified.
+
+=item naked port numbers (e.g. C<1234>)
+
+These are resolved by prepending the local nodename and a colon, to be
+further resolved.
+
+=item hostnames (e.g. C<localhost:1234>, C<localhost>)
+
+These are resolved by using AnyEvent::DNS to resolve them, optionally
+looking up SRV records for the C<aemp=4040> port, if no port was
+specified.
+
+=back
+
 =item $SELF
 
 Contains the current port id while executing C<rcv> callbacks or C<psub>
@@ -449,18 +491,16 @@
 
 =over 4
 
-=item become_public endpoint...
+=item become_public $noderef
 
 Tells the node to become a public node, i.e. reachable from other nodes.
 
-If no arguments are given, or the first argument is C<undef>, then
-AnyEvent::MP tries to bind on port C<4040> on all IP addresses that the
-local nodename resolves to.
-
-Otherwise the first argument must be an array-reference with transport
-endpoints ("ip:port", "hostname:port") or port numbers (in which case the
-local nodename is used as hostname). The endpoints are all resolved and
-will become the node reference.
+The first argument is the (unresolved) node reference of the local node
+(if missing then the empty string is used).
+
+It is quite common to not specify anything, in which case the local node
+tries to listen on the default port, or to only specify a port number, in
+which case AnyEvent::MP tries to guess the local addresses.
 
 =cut
 
@@ -473,6 +513,8 @@
 message - C<$reply[0]> is the port to reply to, C<$reply[1]> the type and
 the remaining arguments are simply the message data.
 
+While other messages exist, they are not public and subject to change.
+
 =over 4
 
 =cut
@@ -584,6 +626,17 @@
 AEMP can use a proven protocol - SSL/TLS - to protect connections and
 securely authenticate nodes.
 
+=item * The AEMP protocol is optimised for both text-based and binary
+communications.
+
+The AEMP protocol, unlike the erlang protocol, supports both
+language-independent text-only protocols (good for debugging) and binary,
+language-specific serialisers (e.g. Storable).
+
+It has also been carefully designed to be implementable in other languages
+with a minimum of work while gracefully degrading fucntionality to make the
+protocol simple.
+
 =back
 
 =head1 SEE ALSO