Thread: Re: [DOCS] Java class documentation

> Could we for now remove the formal class documentation from the DocBook
> source, while keeping the narrative parts, and instead point people to the
> JavaDoc?  Could we make prebuild class documentation in HTML available to
> users, maybe where the jars are downloaded?

Works for me. Not sure if we have rules for building javadoc in our
makefiles, but I'm sure it would be easy to add if necessary. Peter M,
what do you think?

                     - Thomas

Thomas Lockhart writes:

> > Could we for now remove the formal class documentation from the DocBook
> > source, while keeping the narrative parts, and instead point people to the
> > JavaDoc?  Could we make prebuild class documentation in HTML available to
> > users, maybe where the jars are downloaded?
>
> Works for me. Not sure if we have rules for building javadoc in our
> makefiles, but I'm sure it would be easy to add if necessary. Peter M,
> what do you think?

Actually, writing a simplistic javadoc to docbook converter ("doclet")
turned out to be rather easy.  I can create <refentry> pages for the
relevant classes and put them where the current text is.

The result is a bit ugly, actually, because javadoc does not have the rich
structure that docbook has, while none of docbook's structure actually
matches the javadoc format, so it would still be of interest to have the
full javadoc/html set available.

--
Peter Eisentraut      peter_e@gmx.net       http://yi.org/peter-e/

At 16:00 23/02/01 +0000, Thomas Lockhart wrote:
> > Could we for now remove the formal class documentation from the DocBook
> > source, while keeping the narrative parts, and instead point people to the
> > JavaDoc?  Could we make prebuild class documentation in HTML available to
> > users, maybe where the jars are downloaded?
>
>Works for me. Not sure if we have rules for building javadoc in our
>makefiles, but I'm sure it would be easy to add if necessary. Peter M,
>what do you think?

As I just replied to PeterE, I was waiting for 7.1 to be out before
rewriting the docs from scratch. I was waiting because of time restraints
and I didn't want to mess up the exiting docs, especially as I knew you
needed time before release with the docs static.

What I'm working on for the jdbc site is a set of API docs explaining the
PostgreSQL specific extensions, and a set of tutorials. The tutorials range
from the basic stuff (replacing the examples in the source), to writing
Servlets with PostgreSQL, EJB's, Corba etc.

Now a Javadoc->DocBook converter should be easy. In fact you can get
javadoc to do it for you using the Doclet API. Should be real easy to do.

Peter


>                      - Thomas