ant-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Erik Hatcher" <jakarta-...@ehatchersolutions.com>
Subject Re: Official direction for xdocs
Date Sun, 17 Feb 2002 13:43:48 GMT
----- Original Message -----
From: "Bill Burton" <billb@progress.com>

> > Question : What is the official direction for xdocs?
>
> Well, I can't speak officially, but from various discussions on this list,
> it does appear something the committers would like.

Not speaking for all committers, but I think this is a general consensus: we
don't want Ant to keep accumulating "3rd party" tasks - what we want it to
do is more easily plug-in these tasks. So a Coocoon task should live in the
Cocoon codebase and be maintained there.

Are there problems/issues with Ant's optional <stylebook> task?

> Although I'm sure everyone would agree this would be excellent, just doing
> a straight conversion would not help the issue of keeping the docs in sync
> with the tasks.  A better goal would be to generate much of the XML
> documentation directly from the .java task source itself.

We're working on it!  Stay tuned....

> Some recent work on the Myrmidon proposal could be useful in this area.
> XDoclet (http://xdoclet.sourceforge.net/) is being used to generate XML
> task configuration files directly from doclet tags placed in the javadoc
> comments of the tasks, i.e. @ant:task name="javac".  So although
> documentation isn't being generated in this case, it's possible XDoclet
> could be configured for this purpose.  The real benefit of this seems to
> me the ability to generate the documentation for parameter attributes and
> nested elements.  Even better if subclassing is correctly supported in the
> process.

XDoclet handles the inheritance hierarchy such that you could get access to
a superclasses tags/methods/etc from processing a subclass - this requires
the source code for the superclasses (a caveat that must be noted).

>  As it may be akward to maintain the body of the task
> documentation within the javadoc comments, XDoclet supports the notion of
> "Merge Points" allowing the generated XML to include an existing XML file.

Yup!  I'm actually ok with the task source code maintaining the complete
task documentation also, but a merge point is certainly a good idea also.

> Experimenting with documentation ideas like this would be good way anyone
> can help out.  This would probably be a good candidate for a directory
> under proposal/sandbox/.

Again, stay tuned.  I'm working on something like this already and when its
in a presentable shape I'll commit it. And because the metadata is in
Javadoc comments, it won't hurt to actually manipulate our real code base as
well.

    Erik



--
To unsubscribe, e-mail:   <mailto:ant-dev-unsubscribe@jakarta.apache.org>
For additional commands, e-mail: <mailto:ant-dev-help@jakarta.apache.org>


Mime
View raw message