Re: GNOME -- status and future.

[Ryoga no baka <barrows oswego oswego edu>]

On Fri, 6 Feb 1998, Toshio Kuratomi wrote:

> On Fri, 06 Feb, 1998 at 11:30:22PM +0100, Christian Leutloff set free these words:
> > 
> > Can we please use javadoc like documentation!? The comments for the
> > documentation starts with /** 
> > 
> > Here's an example:
> > 
> > /**
> >  * here is the description for the following class, method, variable, ...
> > 
> >  * @author Christian Leutloff 
> >  * @version 0.1, 06.02.1998
> >  */
> > 
> > public class ...
> > {
> >    /**
> >     * the first function
> >     * @param initialValue
> >     * @return something useful
> >     */
> >    public usefulType firstFunc(initType inital)
> >    {
> > ...
> > 
> > 
> > The javadoc program generates from these comments really useful
> > documentation. Look at the JDK documentation which is generated with
> > javadoc.
> > 
> I was thinking this too but here's the question I can't resolve by myself:
> How well does javadoc work with non-OO code?  And with OO C Code (like gtk)?
> 
> -Toshio

It should work fine, I'm pretty sure it mostly uses StreamTokenizer to go
through and catch certain tokens (which are applicable to basically all
C-like languages) and JavaDoc tokens placed in by the programmer - then
take the info it finds (i.e., declarations, imports, methods, JavaDoc
comments, etc) and format it into almost man page-like output.  Elegant
solution actually... (Not that this lazy programmer ever uses it ^o^)  But
it seems like you could easily get man pages and web pages from it
efficently.

It'd probably have to be made to parse methods only instead of classes for
C, (or maybe just leave the capability there for C++/objective C and not
require a class) and a very few other semantical issues would have to be
handled, but it's a solid system.  It produces very nice, helpful output
without too much work :)  I've found the docs for Java's classes
especially helpful.  Books are great, but online help (with hyperlinks) is
nicer sometimes :)

ja ne,

Lester Barrows (Ryoga)  |  ICC Operator   |/~~|        \   _|___ \``
barrows@Oswego.EDU      | SysOp, NeoA88   |   |  |    --+   |   |
www.oswego.edu/~barrows | Linux Inside!       |  |~~    |  ,'  ,'
"Do or Do Not: There is no try."  -Yoda    __/  (l\_  _/  /   /