diff --git a/docs/templates.txt b/docs/templates.txt
index 50f238bf5b..a293bdcff2 100644
--- a/docs/templates.txt
+++ b/docs/templates.txt
@@ -112,7 +112,7 @@ know how to write Python code.
 Comments
 ========
 
-To comment-out part of a template, use the comment syntax: ``{# #}``.
+To comment-out part of a line in a template, use the comment syntax: ``{# #}``.
 
 For example, this template would render as ``'hello'``::
 
@@ -122,6 +122,12 @@ A comment can contain any template code, invalid or not. For example::
 
     {# {% if foo %}bar{% else %} #}
 
+This syntax can only be used for single-line comments (no newlines are
+permitted between the ``{#`` and ``#}`` delimiters). If you need to comment
+out a multiline portion of the template, see the ``comment`` tag, below__.
+
+__ comment_
+
 Template inheritance
 ====================