Author Topic: Doxygen support  (Read 1540 times)

0 Members and 1 Guest are viewing this topic.

Offline Max-Max

Doxygen support
« on: October 29, 2013, 12:55:42 PM »
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.

Example:

Quote
/**
 * 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.
 */

The @retval is preferred over @return because you can specify what each returned value means.
- My code doesn't have bugs. It develops random features...

Offline Markohs

  • DevTeam, Coder/patcher
  • Devotee
  • *
  • Posts: 1560
  • Total likes: 1
  • Helpful: 86
  • Languages: EN,ES,CAT
Re: Doxygen support
« Reply #1 on: October 29, 2013, 01:02:57 PM »
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.

Offline Dwachs

  • DevTeam, Coder/patcher
  • Administrator
  • *
  • Posts: 4121
  • Total likes: 125
  • Helpful: 147
  • Languages: EN, DE, AT
Re: Doxygen support
« Reply #2 on: October 29, 2013, 01:03:56 PM »
(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.
Parsley, sage, rosemary, and maggikraut.