Re: gtk-doc

[Eric Lemings <eric b lemings lmco com>]

Owen Taylor wrote:
> 
> Eric Lemings <eric b lemings lmco com> writes:
> 
> > Hello all,
> >
> > This may sound a little ludicrous and has probably been asked before but
> > has anyone considered modelling gtk-doc after javadoc or making it
> > compatible with javadoc?  I'm just asking because the features of
> > javadoc and documentation generated by it are way ahead of gtk-doc.
> 
> javadoc is, of course, java-specific.
> 
> gtk-doc is GTK+ specific.
> 
> The inline documentation comment format of gtk-doc is in fact
> somewhat modelled after javadoc, but compatibility seems impossible
> due to the fact that they are doing different things.

But not completely different.  There's a few things at least between the
two that are similar.

> Do you have specific suggestions for how you think that the
> documentation produced by gtk-doc could be improved?

Just my humble opinion but the layout of the standard doclet is better
organized (for documenting an object-oriented API) and simply looks
better.  A similar organization and layout would be relatively easy to
adopt in gtk-doc.

The syntax, semantics, and tags of course are different for the most
part because of Java.  But there are several tags that are common (or
could be common) to both gtk-doc and javadoc (@author, @since, @param,
@deprecated, @version, @return, etc).

It would also be nice if gtk-doc supported the concept of a "package"
but that's a high-level design issue.

> (The only real advantage I can think of for javadoc is the ability to
> have have navigation frames.)

That too.  :)

Eric.