ant-user mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Erik Hatcher <>
Subject Re: Simple XDoclet exmple?
Date Mon, 15 Dec 2003 18:33:41 GMT
On Monday, December 15, 2003, at 11:09  AM, Matt Harp wrote:
> I was messing around with it over the weekend to generate 
> documentation on
> my source. Through greps and the xdt I figured out a couple things like
> @ant.attribute group="required" will make the docs say it's required.
> @ant.task ignore="true" will tell the generate to skip that file,
> categrory="mycat" groups the html output into subfolders, etc...

You got it figured out!  Nice detective work!

> So I've been doing a bunch of that and seeing what does what, but all I
> could find on examples was the Javac stuff I mentioned which Peter 
> seems to
> have confirmed that you have to maintain a seperate xml file for stuff 
> like
> that. Can I create a new examples tag and contribute it to the Ant 
> project,
> or is that kind of stuff up to the committee? I don't see why I should 
> have
> to maintain a seperate xml file when the scripting is already setup to 
> parse
> my source file. It would be nice if I could create one huge comment at 
> the
> beginning or end (preferable so people don't have to scroll through 
> comments
> to find the source code) of my source file and seperate it into 
> sections
> with ant tags like ant.example, ant.description, etc...

Just a little bit of background.  XDoclet (for now we'll stick with 
version 1.2, the new 2.0 stuff is a vastly different beast) parses Java 
source code and can extract things from Javadoc comments.  There is no 
way to put a Javadoc comment at the end of a file.  It has to be at the 
class, method, or field levels only.  So, you'd be stuck with putting 
examples in the class level Javadoc tags.  Also, there is a pretty 
horrendous issue with escaping first such that Javadoc is happy, and 
then also such that the XML and ultimately HTML are happy as well.  It 
was a conscious design decision to use XDoclet's merge points to 
integrate in examples so that they are specified in external files.

All that being said, though, it is certainly open for consideration to 
allow for comment samples to be injected also.  The merge point should 
remain, but feel free to add XDoclet tags at the class level that 
accomplish what you want.

> Also, why is the parser/generator ignoring stuff like @author and 
> @version
> tags? Shouldn't it be recognizing these Javadoc tags and including 
> them in
> the generated html?

The parser is not ignoring any Javadoc tag.  It is all there in the 
object model accessible by the template using <XDtNamespace:tagName> 
tags.  So you could easily inject this other information if you like.  
Look at XDoclet's documentation for template tags and go to town.

This information was not needed to match the current documentation.  
@author is not something I think we should carry through.  It is 
open-source and communally owned.  Another point is that in terms of 
generating Ant documentation online to the web, many @author tags have 
e-mail addresses in them and I wouldn't feel right about exposing that 
to the web for spammers to grab (although, Ant's source code is 
crawlable too, so that point is not really that relevant).


To unsubscribe, e-mail:
For additional commands, e-mail:

View raw message