[kaffe] DocBook and Maven proposal

[Jim Pick]

On Sun, 30 Nov 2003 08:10:43 -0800 (PST)
Michael Franz <mvfranz at yahoo.com> wrote:

> I have been thinking about this for the past few days,
> however I am interested in documenting the C code that
> makes up Kaffe.  I am familiar with HeaderDoc from
> Apple and have been looking at GPL alternatives.  I
> have found Doxygen that seems to be very complete and
> has been used in a number of projects.
> http://www.stack.nl/~dimitri/doxygen/ Here is a list
> of other free source code documentation tools.
> http://www.stack.nl/~dimitri/doxygen/links.html

I haven't played with it yet, but Doxygen is extremely popular -- I know
we use it at the place I work.  I think that would be a safe one to go
with.  I'm encouraged that there also seems to be a Maven plugin for it:

  http://maven-plugins.sf.net/maven-doxygen-plugin/

So, theoretically, we can plug it into our Maven-based documentation
generation system.  Again, I expect that we may have to modify a few
Maven plugins and put them in "kaffe-extras" to get the exact output we
want for the published tarballs and the website.

> I took a brief look at gjdoc, but there is only the
> cvs code.  What will be the feature set of gjdoc?

I'll have to let someone else answer that, as I haven't played with it
yet.  I'm hoping it's got the basic Javadoc features so that we use it
as our "Javadoc", and use it with tools such as Ant and Maven.  I think
some IDEs parse the generated HTML documentation, so that might be one
tricky area for compatibility to watch out for.

One more thing I forgot to mention in the proposal - some ideas I have
for the documentation development process:

 1) I want to keep as much development on the mailing list as possible.

 2) I'm thinking of moving the website over to Tomcat - so we can add   
    various webapps to it to do some interesting things.

 3) I've got a half-done regression testing system I would like to
    deploy on the website.  I'd like to hook that into the documentation
    generation system somehow -- primarily so that the documentation
    can say things like "Application XYZ version 1.2.3 passed basic
    regression tests on Platform XX with Kaffe x.y.z".  If we can
    say things like that, then we'll get users for our future
    production releases.

 4) Even though I want all the discussion to happen on-list, I'm
    starting to think that a Wiki might be useful.  It could be used
    to store various bits of quickly mutating information, or for
    editing drafts of half-baked documentation before we commit it
    into CVS.  Opinions?

Anyways, I've got too many ideas - it's slowing me down.  :-)

Cheers,

 - Jim