web: Update docstrings for prepare and on_finish

Document the fact that sometimes prepare() is not called, even if
initialize() and on_finish() are.

Updates #3430
Closes #3431

diff --git a/tornado/web.py b/tornado/web.py
index 289c67384f6d9a0edd8b56c98bb47f716a701767..0303f547eccacd621662432a88312426d185228d 100644 (file)
--- a/tornado/web.py
+++ b/tornado/web.py
@@ -284,7 +284,8 @@ class RequestHandler:
         """Called at the beginning of a request before  `get`/`post`/etc.
 
         Override this method to perform common initialization regardless
-        of the request method.
+        of the request method. There is no guarantee that ``prepare`` will
+        be called if an error occurs that is handled by the framework.
 
         Asynchronous support: Use ``async def`` or decorate this method with
         `.gen.coroutine` to make it asynchronous.
@@ -299,10 +300,14 @@ class RequestHandler:
     def on_finish(self) -> None:
         """Called after the end of a request.
 
-        Override this method to perform cleanup, logging, etc.
-        This method is a counterpart to `prepare`.  ``on_finish`` may
-        not produce any output, as it is called after the response
-        has been sent to the client.
+        Override this method to perform cleanup, logging, etc. This method is primarily intended as
+        a counterpart to `prepare`. However, there are a few error cases where ``on_finish`` may be
+        called when ``prepare`` has not. (These are considered bugs and may be fixed in the future,
+        but for now you may need to check to see if the initialization work done in ``prepare`` has
+        occurred)
+
+        ``on_finish`` may not produce any output, as it is called after the response has been sent
+        to the client.
         """
         pass