I have put in a lot of Doxygen tags in my theme files. Maybe we should work out a standard of what and where to include doxygen tags.
I prefere to have the header files as clean as possible, meaning no function description other than inlines and enums. I browse the header files to quickly see how a class is organized.
In the cc file I prefer to have each function described with in and out params. When you debug, you will end up here and it is very useful to have the documentation at hand at the same time.
* Displays the registered theme_id within the provided rectangle. The theme id points out
* a theme_element_t descendant and calls the overridden Display() routine.
* @param theme_id Id of theme element to be displayed.
* @param frame The bounding box for the drawing area.
* @param align Not used yet.
* @retval true The theme element id was found.
* @retval false The theme element for the id has not been register.
is preferred over @return
because you can specify what each returned value means.
doxygen comments are suposed to go just in the .h, comments in the .cc are just to specify details on the implementation, and prolly just some // will do imho.
(split your post to a separate thread)
I personally prefer to have the documentation in the header.
The @retval tag was unknown to me, can be used as well.
The @author tag does not give much information: it names the creator of the sub-routine, after some time a lot more people modified the routine, so the notion of 'author' loses any sense here.