Inaccurate implementation of {% comment %} presented in custom template tag 'howto' guide

[Julien Phalip]

Two sections (see [1] and [2]) of the custom template tag howto guide illustrate an obsolete implementation (6 years old! -- see r1964) of the built-in {% comment %} tag. Those should be updated either to reflect the new implementation (see in [3]) or to provide a different example.

[1] ​https://docs.djangoproject.com/en/dev/howto/custom-template-tags/#parsing-until-another-block-tag

[2] ​https://docs.djangoproject.com/en/dev/howto/custom-template-tags/#parsing-until-another-block-tag-and-saving-contents

[3] source:django/trunk/django/template/defaulttags.py?rev=16908#L480

[Sebastian Goll]

Here is an attempt at updating the documentation. It still keeps the actual {% comment %} example since I think it's still valid, but adds a note highlighting the differences to the actual implementation.

I still like the simplified {% comment %} example because it leads to the more elaborate {% upper %} tag in the following section. First we parse the node list but simply ignore it, later we actually use it and run a transformation on it.

Coming up with a completely new introductory example seems not necessary, and with the note regarding the actual implementation of {% comment %} it should be clear that this is only an example, usually one would still use the standard {% comment %} tag for actually commenting out template code.

(The note has the added effect of introducing parser.skip_past() which I wasn't aware of until now. – Slightly unrelated, the patch also fixes a missing period in the single-sentence documentation of the actual {% comment %} tag.)

[Chris Beaven]

In [17663]:

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