Documentation - doxygen (was Re: [Plib-devel] Work outstanding.)

[Sam S. <sa...@sp...>]

Hi,

> I'd *really* like to help with this.  Documentation is a pretty vital part
> of getting newbies running, so I'll see what I can do in this regard.  I'm
> thinking of HTML page per class, with member variables and methods
> documented.

Yes, the advantages of having the functions (and variables) documented in the source code can't be under estimated.  I was first
introduced to this when programing on the Amiga (all the public OS functions were documented in this way).  It's _very_ useful.

It means that if someone adds a function they can document before the cvs commit, and the documentation automatically gets updated.
And you won't believe the number of bugs you catch when you start documenting  functions individually :)

> Ideally, a code fragment also, but that relies on having a lot
> of little code fragments!
>
> The Java guys use a neat system called Javadoc, which allows comments
> embedded in code to be cross-compiled into documentation.  You need to use
> some special tags in the comments for the parser to find, but it works
> really nicely if people do it as they go.  Assuming that the comments are
> up to date, a documentation update is as simple as running the Javadoc
> parser through the source.  http://java.sun.com/products/jdk/javadoc/ if
> you're interested.

This is from the Javadoc FAQ:

----
A10.   Can I run javadoc on source files from other languages, such as C, C++ or VisualBasic?

No. Javadoc runs only on Java source code. See the previous question for the explanation. However, other vendors have worked on such
documentation tools. They are listed at the bottom of this page.
----

> There are a number of packages which do the same thing for C++, and I was
> going to have a look at Doxygen, which seems to be quite popular -
> http://www.stack.nl/~dimitri/doxygen/  I'll post some findings about this;
> the last thing I want is to suggest other developers use some weird
> commenting system which most people will just ignore.  It has to be easy
> enough to use that it's almost no effort.

I've used doxygen for my current project and it's very easy to use - I was going to suggest it for plib before this post.  It's
along the lines of:

/**
 * Brief class Description
 * @author Me!
 * @bug Doesn't work - at all!
 * Long class description - HTML tags are <B>allowed</B>
 */
class MyClass {
    public:
        int score; // Current score

        // I know Steve hates the // comments - you can also do this:

        /**
         * Current damage
         */
        int damage;

        /**
         * Brief function description
         * @param x x offset - must be >0
         * @param y y offset - must be > 0
         * @return a new y position
         * Long description here
         * @see AnotherFunction()
         */
        int GenNewY ( int x, int y ) ;
};

Etc.. It actually understands a fair amount of comment formats, so you don't have to use the styles above (although I would suggest
we pick a style and stick to it).

The documentation (for functions), be with the prototype or the declaration.

It will generate it's documentation in HTML, man page format, RTF, and LaTeX.  It will even convert embedded HTML tags into the man,
LaTeX and RTF formats.  It will embed PDF-style links into the LaTeX file so it can be converted to a PDF with hyperlinks intact.

It also automatically generates inheritence diagrams, and also (in the later versions) collaboration diagrams!

If you use doxysearch on the site you can site the documentation online.  This is quite useful as you can search for bug or todo and
get a list of functions back.

IMHO doxygen is fantastic, and I wouldn't hestitate to recommend it.  You can look at the generated documentation for my project
(spacething) at:

http://www.spacething.org/development/docs/

An example of the graphical inheritence diagrams is at:

http://www.spacething.org/development/docs/inherits.html  (scroll down the page a bit)

and an example collaboration diagram:

http://www.spacething.org/development/docs/class_enobject.html

It's a bit of a mess (code and structure wise), but you should be able to see what doxygen is capable of.  On my site it's set up so
that the documentation is automatically regenerated whenever a cvs commit is completed (well actually twenty minutes afterwards).  A
similar autogeneration can be set up on sourceforge (apparently - I haven't tried it yet, but they tell me it's possible).

I've never had any trouble _what__so_ever_ when using the development versions of doxygen - the author has a very high standard.
Since the development release has many more features than the stable, if you choose to use doxygen I'd go with that one.

> Comments?

I really would like to suggest doxygen. :)

Sam