--- AnyEvent-MP/MP.pm	2009/08/06 10:21:48	1.35
+++ AnyEvent-MP/MP.pm	2009/08/06 10:46:48	1.36
@@ -307,8 +307,10 @@
 
 =item reg $port, $name
 
-Registers the given port under the name C<$name>. If the name already
-exists it is replaced.
+=item reg $name
+
+Registers the given port (or C<$SELF><<< if missing) under the name
+C<$name>. If the name already exists it is replaced.
 
 A port can only be registered under one well known name.
 
@@ -317,9 +319,9 @@
 =cut
 
 sub reg(@) {
-   my ($port, $name) = @_;
+   my $port = @_ > 1 ? shift : $SELF || Carp::croak 'reg: called with one argument only, but $SELF not set,';
 
-   $REG{$name} = $port;
+   $REG{$_[0]} = $port;
 }
 
 =item rcv $port, $callback->(@msg)
@@ -334,7 +336,7 @@
 =item rcv $port, [$smartmatch...] => $callback->(@msg), ...
 
 Register callbacks to be called on matching messages on the given full
-port (after converting it to one if required).
+port (after converting it to one if required) and return the port.
 
 The callback has to return a true value when its work is done, after
 which is will be removed, or a false value in which case it will stay
@@ -357,6 +359,22 @@
 element is a string identifying the message. The one-string-only match is
 also the most efficient match (by far).
 
+Example: create a port and bind receivers on it in one go.
+
+  my $port = rcv port,
+     msg1 => sub { ...; 0 },
+     msg2 => sub { ...; 0 },
+  ;
+
+Example: create a port, bind receivers and send it in a message elsewhere
+in one go:
+
+   snd $otherport, reply =>
+      rcv port,
+         msg1 => sub { ...; 0 },
+         ...
+   ;
+
 =cut
 
 sub rcv($@) {
@@ -472,22 +490,30 @@
 
 =item $guard = mon $port, $cb->(@reason)
 
-=item $guard = mon $port, $otherport
+=item $guard = mon $port, $rcvport
+
+=item $guard = mon $port
 
-=item $guard = mon $port, $otherport, @msg
+=item $guard = mon $port, $rcvport, @msg
 
-Monitor the given port and do something when the port is killed.
+Monitor the given port and do something when the port is killed, and
+optionally return a guard that can be used to stop monitoring again.
 
-In the first form, the callback is simply called with any number
-of C<@reason> elements (no @reason means that the port was deleted
+In the first form (callback), the callback is simply called with any
+number of C<@reason> elements (no @reason means that the port was deleted
 "normally"). Note also that I<< the callback B<must> never die >>, so use
 C<eval> if unsure.
 
-In the second form, the other port will be C<kil>'ed with C<@reason>, iff
-a @reason was specified, i.e. on "normal" kils nothing happens, while
-under all other conditions, the other port is killed with the same reason.
+In the second form (another port given), the other port (C<$rcvport)
+will be C<kil>'ed with C<@reason>, iff a @reason was specified, i.e. on
+"normal" kils nothing happens, while under all other conditions, the other
+port is killed with the same reason.
 
-In the last form, a message of the form C<@msg, @reason> will be C<snd>.
+The third form (kill self) is the same as the second form, except that
+C<$rvport> defaults to C<$SELF>.
+
+In the last form (message), a message of the form C<@msg, @reason> will be
+C<snd>.
 
 Example: call a given callback when C<$port> is killed.
 
@@ -495,9 +521,9 @@
 
 Example: kill ourselves when C<$port> is killed abnormally.
 
-   mon $port, $self;
+   mon $port;
 
-Example: send us a restart message another C<$port> is killed.
+Example: send us a restart message when another C<$port> is killed.
 
    mon $port, $self => "restart";
 
@@ -508,12 +534,12 @@
 
    my $node = $NODE{$noderef} || add_node $noderef;
 
-   my $cb = shift;
+   my $cb = @_ ? $_[0] : $SELF || Carp::croak 'mon: called with one argument only, but $SELF not set,';
 
    unless (ref $cb) {
       if (@_) {
          # send a kill info message
-         my (@msg) = ($cb, @_);
+         my (@msg) = @_;
          $cb = sub { snd @msg, @_ };
       } else {
          # simply kill other port
@@ -549,11 +575,15 @@
 sub mon_guard {
    my ($port, @refs) = @_;
 
+   #TODO: mon-less form?
+
    mon $port, sub { 0 && @refs }
 }
 
 =item lnk $port1, $port2
 
+=item lnk $otherport
+
 Link two ports. This is simply a shorthand for:
 
    mon $port1, $port2;
@@ -562,6 +592,18 @@
 It means that if either one is killed abnormally, the other one gets
 killed as well.
 
+The one-argument form assumes that one port is C<$SELF>.
+
+=cut
+
+sub lnk {
+   my $port1 = shift;
+   my $port2 = @_ ? shift : $SELF || Carp::croak 'lnk: called with one argument only, but $SELF not set,';
+
+   mon $port1, $port2;
+   mon $port2, $port1;
+}
+
 =item kil $port[, @reason]
 
 Kill the specified port with the given C<@reason>.