Matthias wrote: > Hmm, allright, here is my take on Doxygen: > > I prefer Doxygen comments in the headers so that headers can be > distributed including the full docs, and no source code is needed. > However, since FLTK is fully OpenSource anyways, and most people seem > to prefer Doxygen comments in the source code instead, let's do it > that way. > > 1: Doxygen start with /*, the following lines start with *, the last > line ends in */ . Single line comments start with ///. All commands > start with a backslash. Please do not use any html, or output to PDF > will look silly. Use \e to emphasize (italics), \b to get a bold word, > \c to get a fixed font for the next word, or \code .. \endcode for a > longer fixed font section. \\ outputs a single \, \@ writes a single > @, same with $, #, &, <, and > > > 2: All comments go into the Source Code (not the header files)
I've just started doxygenating Fl_Button, and have come across some wrinkles in the code, the guidelines, and doxygen: 1. the "no html" rule. Unfortunately doxygen's \c only sets the next word to a constant width (code) font, and text in \code and \endcode pairs ends up in its own boxed paragraph. To format multiple words inline using a constant width font either requires one \c per word. This is fugly for code such as \c FL_ALT \c | \c (FL_F \c + \c10) which can be handled much more readably within <tt> </tt> pairs. 2. Fl_Button.H has: Fl_Button(int,int,int,int,const char* =0) Fl_Button.cxx has: Fl_Button(int X, int Y, int W, int H, const char* l) If I place the doxy-comment in Fl_Button.cxx, the .H form is shown in the generated file. Should I then re-include the elided parameter names in the .H file? 3. Fl_Button.html has a description for the ~Fl_Button() descructor, which is an implicit destructor that is not declared in .H or .cxx I intend to leave this out. C++ programmers should grok destructors. OK, back to doxygenating... _______________________________________________ fltk-dev mailing list [email protected] http://lists.easysw.com/mailman/listinfo/fltk-dev
