[ANet-devel] doxygen for low-level design

[Benoit N. <be...@ma...>]

>On Tue, Dec 04, 2001 at 11:34:36AM +0530, Chirag Kantharia wrote:
>| On Mon, Dec 03, 2001 at 07:56:32PM -0500, Benoit Nadeau wrote:
>| | Chirag: You can start working now on the File Management Wrappers. Place
>| | the "Files.c" in ANet_Daemon/Linux. The two headers you need are
>| | Common/Files.h and Linux/FilesSpecific.h. There are still some
>functions to
>| | add (especially for directory stuff), but at least you can know exactly
>| | what to do for now.
>| Got it. Please ignore my previous mail.
>
>Hi!
>
>I'm still working on the above. Meanwhile, I'd a suggestion: the
>comments in the code could be suitably formatted so that the
>documentation for the code can be automatically generated. For example,
>javadoc, can be used to generate documentation for java class files.
>
>There's something called doxygen which is javadoc equivalent for C/C++,
>but I haven't used it personally. Has anybody on the list used it? Any
>other suggestions for generating the documentation is welcome.

OK. So I looked a bit at doxygen, and it seems to be good.
Look at http://www.stack.nl/~dimitri/doxygen/index.html
Here's an example:

//! A normal member taking two arguments and returning an integer value.
/*!
  \param a An integer argument.
  \param s A constant character pointer.
  \return The test results
  \see Test(), ~Test(), testMeToo() and publicVar()
*/
int testMe(int a,const char *s);

So, it's still readable.
Anyways, I "toyed" a bit with the code, and here's the result:
http://anet.sourceforge.net/doc.tar.gz
HTML starts in html/index.html
PDF is in latex/refman.pdf

Just for fun, look at the graph for the "main.c File Reference".
Wow.

At any rate, it's good enough for me. javadoc used to get on my nerve, but
doxygen's format is good enough for me. You can still make "plain"
comments: I'll be in charge of re-formatting them to doxygen.

Translation: I'll be using doxygen from now on, but you don't have to learn it.

- Benad