Merge branch '1.16'

2 files changed, 17 insertions, 4 deletions

diff --git a/paramiko/channel.py b/paramiko/channel.py
index 057b417b..070009f8 100644
--- a/paramiko/channel.py
+++ b/paramiko/channel.py
@@ -286,7 +286,8 @@ class Channel (ClosingContextManager):
         return an exit status in some cases (like bad servers).
 
         :return:
-            ``True`` if `recv_exit_status` will return immediately, else ``False``.
+            ``True`` if `recv_exit_status` will return immediately, else
+            ``False``.
 
         .. versionadded:: 1.7.3
         """
@@ -300,6 +301,17 @@ class Channel (ClosingContextManager):
         it does, or until the channel is closed.  If no exit status is
         provided by the server, -1 is returned.
 
+        .. warning::
+            In some situations, receiving remote output larger than the current
+            `.Transport` or session's ``window_size`` (e.g. that set by the
+            ``default_window_size`` kwarg for `.Transport.__init__`) will cause
+            `.recv_exit_status` to hang indefinitely if it is called prior to a
+            sufficiently large `.read` (or if there are no threads calling
+            `.read` in the background).
+
+            In these cases, ensuring that `.recv_exit_status` is called *after*
+            `.read` (or, again, using threads) can avoid the hang.
+
         :return: the exit code (as an `int`) of the process on the server.
 
         .. versionadded:: 1.2
diff --git a/paramiko/packet.py b/paramiko/packet.py
index 2be2bb2b..89a514d1 100644
--- a/paramiko/packet.py
+++ b/paramiko/packet.py
@@ -204,9 +204,10 @@ class Packetizer (object):
     def handshake_timed_out(self):
         """
         Checks if the handshake has timed out.
-        If `start_handshake` wasn't called before the call to this function
-        the return value will always be `False`.
-        If the handshake completed before a time out was reached the return value will be `False`
+
+        If `start_handshake` wasn't called before the call to this function,
+        the return value will always be `False`. If the handshake completed
+        before a timeout was reached, the return value will be `False`
 
         :return: handshake time out status, as a `bool`
         """