ant-user mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Jay Glanville" <dic...@nortelnetworks.com>
Subject RE: New doc format and organization
Date Tue, 17 Oct 2000 16:16:38 GMT
I have no knowledge about doclets, so please take my feedback with a grain
of salt.

How hard would it be to write a doclet that would perform a javadoc of the
source tree, ignoring classes that no not extend Task.  Within each of the
remaining classes, only take the class comment, and the comments for the
setter methods, and produces an HTML file for each task.  The doclet would
also be able to produce an index of all tasks.

This might be useful because then you would have a "hierarchy" of task
documentation.  I.e.: if task javac extended matched task, then the
documentation for javac wouldn't need to mention anything about parameters
include/exclude.

Another advantage would be that you would only need to document in one place
-- the code.

The final advantage, you could then "compile" part of your documentation
output.  All the document maintainers would need to do is maintain the rest
of the user manual.  When you consider that the tasks take up 58 pages out
of 76, you've eliminated 76% of the manual maintenance!!

What do you think?

Any takers?  (Sorry, I don't currently have the bandwidth or knowledge of
doclets to be able to do this right now.)

Jay

-----Original Message-----
From: Glenn McAllister [mailto:glennm@ca.ibm.com]
Sent: Tuesday, October 17, 2000 11:20 AM
To: ant-dev@jakarta.apache.org
Cc: ant-user@jakarta.apache.org
Subject: New doc format and organization



Hello all.

I've been working over the docs a bit to reorganize them.  The current
format of one bit index.html file is getting too unwieldy.  The next
logical step is to use framesets with some sort of navigation pane.
Unfortunately, I don't have time to build one that will work across
multiple browsers before our ship date.  So, I've gone for a more LDP
format that has a primary table of contents, with navigation links from one
page to the next.

Now, I don't like this format as it introduces some maintenance headaches.
However, in the end it is probably easier to read (better for the user),
and it also gets us ready for when task docs get dynamically contributed.

Rather than simply commit all the changes into CVS, I'd like some feedback
from everyone.  Attached is a zip with the new docs.  They aren't complete,
so a number of links will be missing or broken (which will be fixed of
course... :-).

Also, how do people feel about CSS?  The basics seem to be fairly well
supported across browsers, but does anyone on the more esoteric platforms
know of any major issues?

Thanks.

(See attached file: ant_docs.zip)

Glenn McAllister
Software Developer. IBM Toronto Lab, (416) 448-3805
"An approximate answer to the right question is better than the
right answer to the wrong question." - John W. Tukey

Mime
View raw message