Hi Peter, I’d personally stick to the following style:

//! Short description.
/*!
\param first First parameter description.
\param second Second parameter description.
\param Nth Nth parameter description.

\returns true if something, false otherwise.

Description (if the short description is not enough). *

\note Possibly some notes. *

\pre Preconditions. *

\sa func1(), func2() *

\todo Possibly some todos. *
*/

Lines marked with an asterisk (*) would be optional (\returns also if it’s a void function). \a could be of course used when referencing a parameter.

But honestly, I’m fine with every readable and simple solution - important is that we would use only that style and try to stick to it in every source. So if anyone has some other ideas/styles, write them ;). Then it would be good to write the specific style into the coding conventions so everyone can read it (and use it).

As for the graphs and diagrams in our documentation - when I want to use something or I’m trying to understand foreign code I first look into the documentation and then to the code (possibly to check implementation or get sure that something is done as I’m expecting). So personally I find inheritance and collaboration diagram quite useful but I’m not using references, referenced by and call graphs because I prefer to get these things from the source code. So I’d either remove them or do something that you’ve suggested (smaller font/line etc.).

Petr