Hi Markus,

I have some more question. Why is the documentation in the implementation file? I was thinking it is in the header file. How can I produce a documentation with doxygen?

I think you asked me about that before but I probably forgot to answer you. There are actually two reasons for writing some of the docs in the source file:

- First thing is, I myself do not use an advanced editor with auto-completion and I often refer to the header file to see the function declarations (if I don’t know them by heart ;-) ). In this case I can get a much better overview if I see a nicely aligned list of functions without any additional docs that will only make the “lookup” harder.

- The second is that if most of the docs are in the source file, then changing the docs would not require a recompilation of all files that have a dependency on the header. Additionally, having more comments in the header could slow down the compilation process (well, with modern computers probably insignificantly but still). Qt for example do not write any docs in the headers for exactly this reason I guess.

Producing Doxygen docs is pretty easy:

cd caltiko-dev
doxygen


You’ll also need the dot tool from GraphViz if you want also some graphs (class hierarchies, call graphs, dependency graphs, etc.) to be generated. Our Doxyfile is configured to use dot.

I would agree if you can model a UML diagram. Do you know a program under Linux where I can produce a UML diagram?

Doxygen has an option for generating UML style class hierarchies but have disabled them because they contain all member functions and variables. I’ve header that Eclipse is capable of generating quite nice UML diagrams from the source code but I haven’t tried it out myself. Maybe some else has more experience with similar stuff?

We manually draw some diagrams in Doxygen comments using the dot format. See for example http://doc.calitko.org/namespace_gnutella.html. The idea is to write architecture documentation for each package (namespace) very much the way I have done for the Gnutella namespace.

Ideas are always wellcome!

Regards,

Peter