iostream: Document the non-deprecation of set_close_callback

diff --git a/tornado/iostream.py b/tornado/iostream.py
index 9f8fdf2578dfe32591eb6ff87875fed4f92b671e..c28dacfba637b4738b4c074b5aaa0960025b7b4c 100644 (file)
--- a/tornado/iostream.py
+++ b/tornado/iostream.py
@@ -593,9 +593,14 @@ class BaseIOStream(object):
     def set_close_callback(self, callback):
         """Call the given callback when the stream is closed.
 
-        This is not necessary for applications that use the `.Future`
-        interface; all outstanding ``Futures`` will resolve with a
-        `StreamClosedError` when the stream is closed.
+        This mostly is not necessary for applications that use the
+        `.Future` interface; all outstanding ``Futures`` will resolve
+        with a `StreamClosedError` when the stream is closed. However,
+        it is still useful as a way to signal that the stream has been
+        closed while no other read or write is in progress.
+
+        Unlike other callback-based interfaces, ``set_close_callback``
+        will not be removed in Tornado 6.0.
         """
         self._close_callback = stack_context.wrap(callback)
         self._maybe_add_error_listener()