Use Comments

<!-- Calculate an XPath child-sequence to -->
<!-- an element node. -->
<!-- The xpath.location template calculates -->
<!-- the absolute path from the root of -->
<!-- the tree to an element node, by default, -->
<!-- the context node. -->

<xsl:template name="xpath.location">
  <!-- The target node -->
  <xsl:param name="node" select="."/>
  <!-- Used in recursive evaluation -->
  <xsl:param name="path" select="''"/>

  <xsl:variable name="next.path">
    <xsl:value-of select="local-name($node)"/>
    ...
<xsl:template>
  • The code is mostly unchanged.

  • Documentation is unstructured.

  • Documentation is second class.

  • Structured comments, like JavaDoc, can be made to work. But burying markup in structured comments when you're working on an XML system would be...odd.