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).
Erik
--------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]