dcsimg
How should I comment Ant targets?
3 posts in topic
Flat View  Flat View
TOPIC ACTIONS:
 

Posted By:   Christian_Ey
Posted On:   Tuesday, May 28, 2002 08:37 AM

Hi there, I created an Ant build file which may be used by many people. Therefore I want to comment the important targets such that someone else can start using my script very quickly. I already use the description attribute of the element which is visible if you execute Ant with the -projecthelp option. But it would be nice to be able to comment targets in more detail, for example to point out properties that are required by the target or to describe the behavior of the target in different conditions. Right now I put this kind of information in simple XML comments. Is there a standardized way to describe targets and does there probably exist something like the javadoc command creating a neat HTML page   More>>

Hi there,



I created an Ant build file which may be used by many people. Therefore I want to comment the important targets such that someone else can start using my script very quickly.



I already use the description attribute of the element which is visible if you execute Ant with the -projecthelp option. But it would be nice to be able to comment targets in more detail, for example to point out properties that are required by the target or to describe the behavior of the target in different conditions. Right now I put this kind of information in simple XML comments.



Is there a standardized way to describe targets and does there probably exist something like the javadoc command creating a neat HTML page as build script documentation?



Thanks!

Chris

   <<Less

Re: How should I comment Ant targets?

Posted By:   Thilo_Calinburg  
Posted On:   Saturday, July 20, 2002 01:51 PM

There is a new tool called "AntDoc" that documents build.xml files like javadoc.


It generates html like you know from javadoc.
You can use it already though some limitations.


http://mapage.noos.fr/edouard.mercier/new/AntDoc_top.html


*greets*

Re: How should I comment Ant targets?

Posted By:   Charles_Jaeger  
Posted On:   Thursday, May 30, 2002 11:17 AM

As a general design rule I would not suggest that all targets have a description entry. This then separates out the -projecthelp output into "main targets" and "subtargets".



My subjective opinion is that the default target for a build.xml files is a "comment" target which echoes the descriptions of main targets.



Subtargets (that should not be called from command line and should not have a description value) should have a target name prepended by "_". (e.g. "_readPropertiesFile" vs "compile"). This way one can identify that all "_" targets are similar to a Java private method.



But that's just my opinion.



I agree that something like a Javadoc capability for ant would be beneficial. Perhaps the solution is to create a custom documentation task.



--cj

Re: How should I comment Ant targets?

Posted By:   Erik_Hatcher  
Posted On:   Thursday, May 30, 2002 06:43 AM

Unfortunately there is not a "javadoc" for Ant, but using XML comments like works nicely for internal documentation, and as you mentioned the description attributes of . You could use XSLT to document an Ant build file, but there is nothing built-in to provide this.
About | Sitemap | Contact