Document websocket error handling change (and StreamClosedError).

docs/iostream.rst

@@ -43,3 +43,8 @@
 
    .. autoclass:: PipeIOStream
       :members:
+
+   Exceptions
+   ----------
+
+   .. autoexception:: StreamClosedError

docs/releases/next.rst

@@ -229,6 +229,9 @@ Multiple modules
 `tornado.websocket`
 ~~~~~~~~~~~~~~~~~~~
 
+* `.WebSocketHandler` now catches `.StreamClosedError` and runs
+  `~.WebSocketHandler.on_close` immediately instead of logging a
+  stack trace.
 * New method `.WebSocketHandler.set_nodelay` can be used to set the
   ``TCP_NODELAY`` flag.
 

tornado/iostream.py

@@ -48,6 +48,12 @@ except ImportError:
 
 
 class StreamClosedError(IOError):
+    """Exception raised by `IOStream` methods when the stream is closed.
+
+    Note that the close callback is scheduled to run *after* other
+    callbacks on the stream (to allow for buffered data to be processed),
+    so you may see this error before you see the close callback.
+    """
     pass