FLTK 2.0 and FLTK 1.3 and up use Doxygen with the JavaDoc comment style to document all classes, structures, enumerations, methods, and functions. Doxygen comments are mandatory for all FLTK header and source files, and no FLTK release will be made without complete documentation of public APIs. Here is an example of the Doxygen comment style:
class FL_EXPORT Foo : public Widget {
int private_data_;
public:
/**
Creates a Foo widget with the given position and label.
This description text appears in the documentation for the
method's implementation.
References to parameters \p X, \p Y, \p W, \p H are
mentioned this way.
\param[in] X,Y,W,H Position and size of widget
\param[in] L Optional label (default is 0 for no label)
*/
Foo(int X, int Y, int W, int H, const char *L = 0) {
..implementation here..
}
};
I do like when (*)s run down left margin of all comments; easier to differentiate comments from code in large doc blocks. -Erco 3/14/09 11:26 AM
Yes, same here. I usually align them in the second column. -Matthias Melcher 3/14/09 11:02 PM
Duncan doesn't like (*)s down the left because it complicates paragraph reformatting.. passing that on. -Erco 3/15/09 1:12 PM
Albrecht says this was already discussed and decision was *no stars* down the left, so I modified the examples here. -Erco 3/15/09 2:30 PM
Note: fltk2 uses QT /*! style comments, whereas fltk1 uses /** as described above. Should standard reflect this? -Erco 3/15/09 2:36 PM
Essentially, a comment starting with /** before the class or method defines the documentation for that class or method. These comments should appear in the header file for classes and inline methods and in the code file for non-inline methods.
In addition to Doxygen comments, block comments must be used
liberally in the code to describe what is being done. If what
you are doing is not "intuitively obvious to a casual observer",
add a comment! Remember, you're not the only one that has to
read, maintain, and debug the code.
Never use C++ comments in C code files or in header
files that may be included from a C program. Normally, fltk C files have ".c" and ".h" file extensions, and C++ have ".cxx" and ".H". Currently there are a few exceptions; filename.H and Fl_Exports.H both get interpreted by C and C++, so you must use C style comments in those. (Otherwise builds on strict platforms like SGI will fail).
| /** Here's a bullet list: - Apples - Oranges Here's a numbered list: -# First thing -# Second thing */ | /** Here's a bullet list: <ul> <li> Apples</li> <li> Oranges</li> </ul> Here's a numbered list: <ol> <li> First thing</li> <li> Second thing</li> <ol> * |
Temporary code and code that has a known issue MUST be documented in-line with the following (Doxygen) comment style:
/** \todo this code is temporary */
\todo items are listed by Doxygen making it easy to locate any code that has an outstanding issue or code that should be removed or commented out prior to a release.
Classes and structures start with a comment block that looks like the following:
/**
A brief description of the class/structure.
A complete description of the class/structure.
*/
class MyClass {
..
};
Enumerations start with a comment block that looks like the following:
/**
A brief description of the enumeration.
A complete description of the enumeration.
*/
enum MyEnum {
...
};
Each enumeration value must be documented in-line next to the corresponding definition as follows:
enum MyEnum {BLACK, /**< The color black. */RED, /**< The color red. */GREEN, /**< The color green. */YELLOW, /**< The color yellow. */BLUE /**< The color blue. */};/* C++ STYLE */enum MyEnum {BLACK, //< The color black.RED, //< The color red.GREEN, //< The color green.YELLOW, //< The color yellow.BLUE //< The color blue.};
Functions and methods start with a comment block that looks
like the following:
/**
A brief description of the function/method.
A complete description of the function/method.
Passing mention of arguments \p a and \p b.
Optional code example:
\code
int w=0, h=0; // must be 0!
fl_measure(s,w,h);
\endcode
\param[in] X,Y,W,H Description of all four variables at once
\param[in] a What "a" input is.
\param[in] b What "b" input is.
\param[out] out1 What "out1" output is
\param[out] out2 What "out2" output is
\returns What this function/method returns.
\see Related methods foo1(), foo2(), foo3()
*/
int my_function(int a, int b, float &out1, float &out2) {
...implementation...
}
Each parameter is documented using \param[in|out]. The return value is documenting using \return; omit the return value comment if
the function/method does not return a value or is a constructor. Use \see to refer to other, related
functions/methods. Passing mention of parameters in docs should use "\p varname". (Use \p instead of \a; \p shows in a different font face, making it clearer to see than \a in the index and in printouts)
Note doxygen will check your \param[in/out] xxx variable names, and will complain if they don't match the method's declaration variable names. This is a good thing, so definitely
use it so we can see discrepancies between the code and the docs. Note that doxygen does NOT check \p names for consistency.
Function/method documentation must be placed next to the
corresponding code. (Rule: "Put the docs where the code implementation is.") Comments for in-line functions and methods
in header files are placed in the header file.
Use \code and \endcode when code examples are needed. Text within \code is exempt from html and doxygen escape code parsing, so you don't have to escape characters <, >, &, etc. as you would normally. Be careful not to embed C style comments within \code, as it will conflict with the doxygen comment block.
Since methods are being sorted alphabetically by doxygen, like-kind methods should be 'grouped' together by using "\see Related methods xxx(), yyy().."; put this below the \param[]s and \returns (as shown above).
In the above, I changed all @param's to \param because that seems to be what's actually in the code. -Erco 3/14/09 10:59 AM
Members and variables can be documented in one of two ways; in block comment form as follows:
/**
A brief description of the member/variable.
A complete description of the member/variable.
*/
int my_variable_;
or in the preferred form as in-line comments as follows:
int my_variable_; ///< A brief description of the member/variable in a C++ file
int my_variable_; /**< A brief description of the member/variable in a C file. */
