diff --git a/doc/zmq_disconnect.txt b/doc/zmq_disconnect.txt
index cd4e3689..b452dee1 100644
--- a/doc/zmq_disconnect.txt
+++ b/doc/zmq_disconnect.txt
@@ -9,17 +9,25 @@ zmq_disconnect - Disconnect a socket
 
 SYNOPSIS
 --------
-int zmq_disconnect (void '*socket', const char '*endpoint');
+*int zmq_disconnect (void '*socket', const char '*endpoint');*
 
 
 DESCRIPTION
 -----------
 The _zmq_disconnect()_ function shall disconnect a socket specified
 by the 'socket' argument from the endpoint specified by the 'endpoint'
-argument. 
+argument. Any outstanding messages physically received from the network but not
+yet received by the application with _zmq_recv()_ shall be discarded. The
+behaviour for discarding messages sent by the application with _zmq_send()_ but
+not yet physically transferred to the network depends on the value of the
+_ZMQ_LINGER_ socket option for the specified 'socket'.
 
 The 'endpoint' argument is as described in linkzmq:zmq_connect[3]
 
+NOTE: The default setting of _ZMQ_LINGER_ does not discard unsent messages;
+this behaviour may cause the application to block when calling _zmq_term()_.
+For details refer to linkzmq:zmq_setsockopt[3] and linkzmq:zmq_term[3].
+
 
 RETURN VALUE
 ------------
diff --git a/doc/zmq_setsockopt.txt b/doc/zmq_setsockopt.txt
index 67a2ad2e..7c5bde3f 100644
--- a/doc/zmq_setsockopt.txt
+++ b/doc/zmq_setsockopt.txt
@@ -215,24 +215,24 @@ ZMQ_LINGER: Set linger period for socket shutdown
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 The 'ZMQ_LINGER' option shall set the linger period for the specified 'socket'.
 The linger period determines how long pending messages which have yet to be
-sent to a peer shall linger in memory after a socket is closed with
-linkzmq:zmq_close[3], and further affects the termination of the socket's
-context with linkzmq:zmq_term[3]. The following outlines the different
-behaviours:
+sent to a peer shall linger in memory after a socket is disconnected with
+linkzmq:zmq_disconnect[3] or closed with linkzmq:zmq_close[3], and further
+affects the termination of the socket's context with linkzmq:zmq_term[3]. The
+following outlines the different behaviours:
 
 * The default value of '-1' specifies an infinite linger period. Pending
-  messages shall not be discarded after a call to _zmq_close()_; attempting to
-  terminate the socket's context with _zmq_term()_ shall block until all
-  pending messages have been sent to a peer.
+  messages shall not be discarded after a call to _zmq_disconnect()_ or
+  _zmq_close()_; attempting to terminate the socket's context with _zmq_term()_
+  shall block until all pending messages have been sent to a peer.
 
 * The value of '0' specifies no linger period. Pending messages shall be
-  discarded immediately when the socket is closed with _zmq_close()_.
+  discarded immediately after a call to _zmq_disconnect()_ or _zmq_close()_.
 
 * Positive values specify an upper bound for the linger period in milliseconds.
-  Pending messages shall not be discarded after a call to _zmq_close()_;
-  attempting to terminate the socket's context with _zmq_term()_ shall block
-  until either all pending messages have been sent to a peer, or the linger
-  period expires, after which any pending messages shall be discarded.
+  Pending messages shall not be discarded after a call to _zmq_disconnect()_ or
+  _zmq_close()_; attempting to terminate the socket's context with _zmq_term()_
+  shall block until either all pending messages have been sent to a peer, or the
+  linger period expires, after which any pending messages shall be discarded.
 
 [horizontal]
 Option value type:: int