Introduction
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.
The Standard
Tags
Tags are marked with @tag tag, followed by a space, then a description of the tag.
Example:
<!--
@tag input input for amount paid
-->
<input type="number" id="amountPaid" />
Attributes
Attributes are marked up with the @attribute tag, followed by a space, then a description of the attribute.
Example:
<!--
@tag input
@attribute step Allows entry of decimals into a number field, without
triggering validation errors.
-->
<input
type="number"
span="any"
/>
Values
Attribute values are marked up with the @value tag, followed by a space, then a description of the value.
Example:
<!--
@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>