ant-user mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Glenn McAllister" <gle...@ca.ibm.com>
Subject RE: New doc format and organization
Date Tue, 17 Oct 2000 16:36:33 GMT


Well, my knowledge of doclets is pretty good, so I'll take a stab at
discussing your proposal with you.

In theory, there isn't a dang thing wrong with what you propose, except for
two things.  Creating a custom doclet isn't that hard (although I could
kill the guys at Sun for using only static methods... it pretty much
precludes inheriting without going through a bunch of backflips), in this
case it would just be a SMOP.  What is hard is to get good comments.

One of the biggest problems we have with Javadoc is developers putting in
lousy HTML tags.  There is usually a bit of churn in trying to get the
developers to update their code with changes, either to the HTML tagging or
simply to grammar and readability.

The other problem with the doclet proposal is that API docs are intended
more as either an implimentation guide or a method usage guide.  A broader
programming/usage guide is often hard to implement inside doc comments.
Now, this can be alieviated by using the package and overview HTML files,
so this argument is getting weaker.  Nonetheless, using doc comments as
both method usage and attribute usage guides could get tricky.

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


Please respond to ant-user@jakarta.apache.org

To:   "Ant-User (text)" <ant-user@jakarta.apache.org>
cc:
Subject:  RE: New doc format and organization

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




Mime
View raw message