Document the fact that add_handlers should only be called once for each

host_pattern.

diff --git a/tornado/web.py b/tornado/web.py
index f0bfaaff6134e598e832f1e906d1de1117629bc0..a8e1b6c7e1b432e85f90856b190bbbf64e88f49d 100644 (file)
--- a/tornado/web.py
+++ b/tornado/web.py
@@ -1018,7 +1018,13 @@ class Application(object):
             autoreload.start()
 
     def add_handlers(self, host_pattern, host_handlers):
-        """Appends the given handlers to our handler list."""
+        """Appends the given handlers to our handler list.
+
+        Note that host patterns are processed sequentially in the
+        order they were added, and only the first matching pattern is
+        used.  This means that all handlers for a given host must be
+        added in a single add_handlers call.
+        """
         if not host_pattern.endswith("$"):
             host_pattern += "$"
         handlers = []