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) 4: The /** line is reserved for references if needed, for example /** \class Fl_Widget ... to describe the class itself from within the source file /** \fn color(Fl_Color) ... to describe an inline function that only exists in the header file 3: The second line of comment is always a brief description, followed by a full stop, followed by an empty line: /** * This function returns the current widget color. * * It returns the color given by bla bla... 4: The next lines describe the function in more words, followed by an emty line 5: Every parameter must be named and described now. If the parameter is a call-by-reference, it must state if it is used for input or output. If you write the name of a parameter anywhere except right after \param, prepend it with a \p * \param[in] x, y the position of the widget. \p x should be positive * \param[in,out] w suggest a width on input, then return the actual width * \param[out] h returning the height of the label 6: Next, describe what the function returns. If there are specific eturn values, use \retval * \retval 0 if the function succeeded * \retval -1 if the file was not found * \retval -2 if the file was found but could not be opened or use \return otherwise * \return the product of the two parameters, or -1.0 if there was an error 7: Every block should have a \see block which references similar functions or the same family. Make sure to repeat the parameter types, or cross linking will be messed up: * \see color(Fl_Color), color(), Fl::color(Fl_Color, unsigned int) 8: If you feel like this function still needs some work, you can add a \todo. If this is a new function for 1.3, please add \since 1.3.0. There are tons of other tags, but I would not worry about them now. Matthias ---- http://robowerk.com/ _______________________________________________ fltk-dev mailing list [email protected] http://lists.easysw.com/mailman/listinfo/fltk-dev
