We like to use XSLT over our build files to generate documentation of our 
build scripts.  Currently we have defined a macrodef called documentation that 
takes a type attribute (such as "usage", "example", "introduction", etc.) and 
a content attribute ("text" or "html"), but doesn't do anything at all.  We 
then use the macro in various places to document what we are doing.

However, to use this inside a macrodef, we have to put it inside the 
sequential section instead of in the macrodef header.

It would be nice if there were a built-in ability to put in a <documentation 
type="foo" content="bar"> type of construct anywhere in your build script.  
This would allow tools to get documentation of the script without having to 
parse XML comments.