Wouldn't it be nice if there was a consistent markup standard for code comments in HTML?
Some scenarios where rigorous code comments could be useful:
- Non-intuitive or hackish usage of HTML tags, elements and attributes, where explanation would help
- Other uses of non-visual elements
- Accessibility features
- Search engine optimisation (SEO) features
Introducing HTMLDoc - a simple markup language for augmenting HTML tags and attributes with descriptive comments, which can be used to generate structured documentation.
Tags are marked with @tag tag, followed by a space, then a description of the tag.
<!-- @tag input input for amount paid --> <input type="number" id="amountPaid" />
Attributes are marked up with the @attribute tag, followed by a space, then a description of the attribute.
<!-- @tag input @attribute step Allows entry of decimals into a number field, without triggering validation errors. --> <input type="number" span="any" />
Attribute values are marked up with the @value tag, followed by a space, then a description of the value.
<!-- @tag input @attribute class @value has-clear-button Pulls the spin-button to the left, to make space for the clear button. --> <input type="number" class="has-clear-button" /> <button class="clear-button">Clear</button>