@use HTMLDoc - a standard for documenting HTML

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>