Commenting/generate documentation from an ant script

["Scot P. Floess" <fl...@mindspring.com>]

I have what may be either a stupid questions or a silly ones...but I 
can't find an answer (perhaps my google search is using the wrong key 
words)...

As part of one of my open source projects I am working on some (I hope) 
reusable Ant scripts.  I have some macro definitions, etc.  I was 
wondering if there is any standard out there on how one should document 
macros?  Sorta like javadoc notation or some "preferred" way of internal 
documentation.

Another question, is there a tool to generate java-doc like HTML against 
Ant scripts?  Or does one need to handcraft their own web pages?

Final question (wow it just keeps going):  what about unit test cases 
for one's Ant scripts.  For instance, supposing one writes macros - what 
do people do for unit test cases?  Presently, I have a script file that 
imports the macro scripts file and calls out to the macros...then I 
evaluate properties, etc for accuracy.  However, I was wondering if 
there is some "preferred" mechanism as well...

Thanks again :)

Scot

-- 
Scot P. Floess
27 Lake Royale
Louisburg, NC  27549

252-478-8087 (Home)
919-754-4592 (Work)

Chief Architect JPlate  http://sourceforge.net/projects/jplate
Chief Architect JavaPIM http://sourceforge.net/projects/javapim


---------------------------------------------------------------------
To unsubscribe, e-mail: user-unsubscribe@ant.apache.org
For additional commands, e-mail: user-help@ant.apache.org

RE: Commenting/generate documentation from an ant script

[bill/wilandra <bi...@wilandra.com>]

Hi Scot, I use the attached XSL file to generate documentation for my Ant
files. This is an extension of the XSL stylesheet found at
http://www-106.ibm.com/developerworks/xml/library/x-antxsl/examples/example2
/ant2html.xsl modified to pick up some new stuff and to always display the
documentation attribute and comments. You can put a description attribute on
the target and macrodef elements. That is where I put my documentation. The
XSL file will generate an HTML page with a sorted list of targets, macros,
included files, etc. with appropriate links to the section where the item is
displayed. It also tries to format the items with some indents. The
formatting is not always successful but usually close enough for me. This
only works on a single Ant file so there is no linking to targets in other
Ant files. I would like to extend it to do that but have no idea how.

It works in Firefox, Opera, and IE. Once in a while I get some glitch in IE
but since I don't use IE any more I don't worry about it.

HTH Bill 

-----Original Message-----
From: Scot P. Floess [mailto:floess@mindspring.com] 
Sent: Friday, May 19, 2006 8:39 AM
To: Ant Users List
Subject: Commenting/generate documentation from an ant script

I have what may be either a stupid questions or a silly ones...but I can't
find an answer (perhaps my google search is using the wrong key words)...

As part of one of my open source projects I am working on some (I hope)
reusable Ant scripts.  I have some macro definitions, etc.  I was wondering
if there is any standard out there on how one should document macros?  Sorta
like javadoc notation or some "preferred" way of internal documentation.

Another question, is there a tool to generate java-doc like HTML against Ant
scripts?  Or does one need to handcraft their own web pages?

Final question (wow it just keeps going):  what about unit test cases for
one's Ant scripts.  For instance, supposing one writes macros - what do
people do for unit test cases?  Presently, I have a script file that imports
the macro scripts file and calls out to the macros...then I evaluate
properties, etc for accuracy.  However, I was wondering if there is some
"preferred" mechanism as well...

Thanks again :)

Scot

--
Scot P. Floess
27 Lake Royale
Louisburg, NC  27549

252-478-8087 (Home)
919-754-4592 (Work)

Chief Architect JPlate  http://sourceforge.net/projects/jplate
Chief Architect JavaPIM http://sourceforge.net/projects/javapim


---------------------------------------------------------------------
To unsubscribe, e-mail: user-unsubscribe@ant.apache.org For additional
commands, e-mail: user-help@ant.apache.org