Cp-tools Javadoc Overview (was Re: Classpath API javadoc)

[Julian Scheid]

Mark Wielaard wrote:
>
> I have not tried out the texidoclet for the Classpath Tools project yet.
> Source can be found <http://savannah.gnu.org/cgi-bin/viewcvs/cp-tools/>
> I don't know if there has been an official release yet.
>



Hi there,

let me take this opportunity and give you a brief overview of
our doings at cp-tools.

We have a couple of javadoc-related tools underway:

- "Gjdoc" is an alternative javadoc driver. That is, it scans
Java source files, extracts all javadoc related information
and provides that to whichever doclet is plugged into it
via the Doclet API.
When finished, it will provide basically the same output
as Sun's javadoc tool does, but currently there are some minor
deviations and also some stuff missing.

- "TexInfo doclet" (formerly TexiDoclet) takes that information
(from either Gjdoc or Sun's Javadoc) and generates TexInfo code
from it, which in turn can be converted to Info pages for viewing
in Emacs or with the Info standalone tool. The TexInfo code is
not intended for converting it into a printable form, though.

- "XML doclet" puts all information into an XML file. I have
written an XSLT style sheet which generates HTML documentation
from that XML file. The generated HTML has a structure similar
to that of Suns "Standard Doclet" output, but is currently
missing a couple of things (for example, a full class tree
page, serialization pages, package overview page)

All three tools still have some quirks, with TexInfo doclet
being the most complete and best tested. While not officially
released by now, it should be complete enough for experimental
usage. So please go ahead and give it a try.

In contrast, whoever works on the documentation should not
primarily rely on Gjdoc and the XML/XSLT solution at this
time, because  when problems occur it will be hard to tell
where they originate (Problems with the inline documentation?
Gjdoc doesn't provide all/provides wrong information? Bugs
in XML doclet? In the XSLT sheet?)

Anyway, it would be great if you'd give all these tools a try
and report any problems back to cp-tools. After all, the
Classpath source is the ideal test case for the tools. And we
are not that far away from a point where we can generate
nice-looking and complete docs in both TexInfo and HTML format.
The more feedback we get, the sooner we can reach this goal.

If there are any build issues with the tools (especially with
Gjdoc and the XML doclet, which are not yet autoconf'ing AFAIK)
I'll be glad to help - just post to <address@hidden>.

Philip, if you intend to work on the API docs you may want to
consider joining the cp-tools-discuss list.

--Julian