Problem: adapt, clarify docs ZMQ_ROUTER_MANDATORY

Solution:

* Document the new behaviour when generating 'ZMQ_POLLOUT' events
  for ZMQ_ROUTER sockets with 'ZMQ_ROUTER_MANDATORY' set to `1`
* Add clarifications for 'ZMQ_ROUTER' socket when
  'ZMQ_ROUTER_MANDATORY' is set to `1`

doc/zmq_setsockopt.txt

@@ -745,6 +745,11 @@ code if the SNDHWM is reached and ZMQ_DONTWAIT was used. Without ZMQ_DONTWAIT
 it will block until the SNDTIMEO is reached or a spot in the send queue opens
 up.
 
+When ZMQ_ROUTER_MANDATORY is set to `1`, 'ZMQ_POLLOUT' events will be generated
+if one or more messages can be sent to at least one of the peers. If
+ZMQ_ROUTER_MANDATORY is set to `0`, the socket will generate a 'ZMQ_POLLOUT'
+event on every call to 'zmq_poll'.
+
 [horizontal]
 Option value type:: int
 Option value unit:: 0, 1

doc/zmq_socket.txt

@@ -504,15 +504,22 @@ prepend a message part containing the _identity_ of the originating peer to the
 message before passing it to the application. Messages received are fair-queued
 from among all connected peers. When sending messages a 'ZMQ_ROUTER' socket shall
 remove the first part of the message and use it to determine the _identity_ of
-the peer the message shall be routed to. If the peer does not exist anymore
-the message shall be silently discarded by default, unless 'ZMQ_ROUTER_MANDATORY'
-socket option is set to '1'.
+the peer the message shall be routed to. If the peer does not exist anymore, or
+has never existed, the message shall be silently discarded. However, if
+'ZMQ_ROUTER_MANDATORY' socket option is set to '1', the socket shall fail
+with EHOSTUNREACH in both cases.
 
 When a 'ZMQ_ROUTER' socket enters the 'mute' state due to having reached the
 high water mark for all peers, then any messages sent to the socket shall be dropped
 until the mute state ends. Likewise, any messages routed to a peer for which
-the individual high water mark has been reached shall also be dropped,
-unless 'ZMQ_ROUTER_MANDATORY' socket option is set.
+the individual high water mark has been reached shall also be dropped. If,
+'ZMQ_ROUTER_MANDATORY' is set to '1', the socket shall block or return EAGAIN in
+both cases.
+
+When a 'ZMQ_ROUTER' socket has 'ZMQ_ROUTER_MANDATORY' flag set to '1', the
+socket shall generate 'ZMQ_POLLIN' events upon reception of messages from one
+or more peers. Likewise, the socket shall generate 'ZMQ_POLLOUT' events when
+at least one message can be sent to one or more peers.
 
 When a 'ZMQ_REQ' socket is connected to a 'ZMQ_ROUTER' socket, in addition to the
 _identity_ of the originating peer each message received shall contain an empty