TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
Subject:RE: Has Anyone Used Javadoc From:"Steve Read" <stephenread -at- earthlink -dot- net> To:"TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com> Date:Tue, 6 Jun 2000 17:10:46 -0600
I also have some Javadoc problems I'm trying to work out.
Some of my givens:
- My developers are very happy with Javadoc, format-wise.
- I'm writing a programmer's guide for 8 or 10 Java apps.
- I need to provide this kind of information (a quote from the development
"I like the approach of
walking through the app then outlining the relevant classes. I would like a
listing of all the major classes and their methods and how they interact in
a flow diagram also included, then a diagram walking through the available
options (this can be a flowchart too.)
at the end of the doc, a would like a list of the possible exceptions
thrown and an outline of when each case can occur, i.e. invalid password
is suplied causing login to fail and an exception to be logged."
- I'm going to produce either a pdf or html as the programmer's guide
output. I don't know which yet, but I can fire up the Javadoc output from
either, so I don't see a problem there.
- I'm in a hurry (natch).
The problem I see is that, because Javadoc sucks out the comments from the
code to create the html, my "enhancements" to the comments in the form of
things like usage notes or whatever will be nuked the next time we run
Javadoc. I see a huge maintenance headache looming on the horizon, in the
form of cutting and pasting this text into the Javadoc output.
Has anyone tried to build something like this, and have you had my
particular set of problems, and if I buy you a cupcake, will you help?