ant-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Erik Hatcher" <jakarta-...@ehatchersolutions.com>
Subject XDocs Proposal
Date Wed, 27 Feb 2002 05:43:31 GMT
From: <ehatcher@apache.org>

> ehatcher    02/02/26 21:25:36
>
>   Added:       proposal/xdocs/src/org/apache/tools/ant/xdoclet
>                         AntSubTask.java AntTagsHandler.java
>   Log:
>   First pass at XDoclet generation of Ant task documentation.

Ok folks!  Here it is.

The long awaited XDoclet documentation generator.  While it still has some
loose ends and issues to resolve, it works great for me on the taskdefs
directory (did not try the subdirectories, but should work similarly there).

To try it out should be fairly straightforward.  I committed my home-built
xdoclet.jar as it has to be built from CVS currently to accomodate some bug
fixes that I needed.

You'll also need log4j.jar which my build file assumes lives in
jakarta-ant/lib/optional directory, but just -Dlog4j.jar=/path/to/log4j.jar
and you'll be all set.

Just run the default target and in the build directory a gen directory will
be created with the package subdirectories down to taskdefs.  In there
you'll see a bunch of .xml files that have extracted out Javadoc comments,
attribute setters, sub-elements, and even addText (which is denoted by
<body>).

There are a few tasks that don't have the same name as their class name
(<style>, for example).  I commited a change to Exit.java so you can see how
it works - it defaults to picking up @ant:task name="..." or the lowercase
version of the classname (minus "Task" suffix).  I did not inject the
@ant:task category="..." into the XML yet, but that is the goal so that we
can segregate these things in our manual by type of functionality similar to
Diane's work.

I'm sure there are many other issues that need to be addressed, but I hope
you'll find this gets us *darn close*.  It required some custom XDoclet
coding - a custom subtask and a custom tag handler, mostly simple stuff once
I dug in their source code a bit to get the bigger picture.  Some
interesting issues are: How do we deal with enumerated types? (since its
building off the source code, I can't just instantiate and call the method
to get the values - or, could I assume the class is available to
instantiate?  we are running *in* Ant after all!)

Let me know if you spot any idiosyncracies in what it generates - I've only
spot checked some things to make sure it was looking decent.  I wrapped all
possible XML breaking things in CDATA - maybe its better to encode strings
first?

Anyway, have at it!  I look forward to your feedback and improvements.

    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