Fixed #16939 -- Inaccurate implementation of {% comment %} presented in custom template tag 'howto' guide. Thanks sebastian for the patch.

git-svn-id: http://code.djangoproject.com/svn/django/trunk@17663 bcc190cf-cafb-0310-a4f2-bffc1f526a37

2 files changed, 10 insertions, 2 deletions

diff --git a/docs/howto/custom-template-tags.txt b/docs/howto/custom-template-tags.txt
index 0b962f8863..751411c446 100644
--- a/docs/howto/custom-template-tags.txt
+++ b/docs/howto/custom-template-tags.txt
@@ -1155,7 +1155,7 @@ Template tags can work in tandem. For instance, the standard
 To create a template tag such as this, use ``parser.parse()`` in your
 compilation function.
 
-Here's how the standard :ttag:`{% comment %}<comment>` tag is implemented:
+Here's how a simplified ``{% comment %}`` tag might be implemented:
 
 .. code-block:: python
 
@@ -1168,6 +1168,14 @@ Here's how the standard :ttag:`{% comment %}<comment>` tag is implemented:
         def render(self, context):
             return ''
 
+.. note::
+    The actual implementation of :ttag:`{% comment %}<comment>` is slightly
+    different in that it allows broken template tags to appear between
+    ``{% comment %}`` and ``{% endcomment %}``. It does so by calling
+    ``parser.skip_past('endcomment')`` instead of ``parser.parse(('endcomment',))``
+    followed by ``parser.delete_first_token()``, thus avoiding the generation of a
+    node list.
+
 ``parser.parse()`` takes a tuple of names of block tags ''to parse until''. It
 returns an instance of ``django.template.NodeList``, which is a list of
 all ``Node`` objects that the parser encountered ''before'' it encountered
diff --git a/docs/ref/templates/builtins.txt b/docs/ref/templates/builtins.txt
index 1efc3e2621..0251dcbca4 100644
--- a/docs/ref/templates/builtins.txt
+++ b/docs/ref/templates/builtins.txt
@@ -51,7 +51,7 @@ Defines a block that can be overridden by child templates. See
 comment
 ^^^^^^^
 
-Ignores everything between ``{% comment %}`` and ``{% endcomment %}``
+Ignores everything between ``{% comment %}`` and ``{% endcomment %}``.
 
 .. templatetag:: csrf_token