49 lines
2.0 KiB
Plaintext
49 lines
2.0 KiB
Plaintext
|
This is a basic rule-of-thumb for using Doxygen comments to document code
|
||
|
|
|
||
|
|
/**
|
||
|
|
* A brief history of JavaDoc-style (C-style) comments.
|
||
|
|
*
|
||
|
|
* This is the typical JavaDoc-style C-style comment. It starts with two
|
||
|
|
* asterisks.
|
||
|
|
*
|
||
|
|
* @param theory Even if there is only one possible unified theory. it is just a
|
||
|
|
* set of rules and equations.
|
||
|
|
*/
|
||
|
|
void cstyle( int theory );
|
||
|
|
|
||
|
|
/*******************************************************************************
|
||
|
|
* A brief history of JavaDoc-style (C-style) banner comments.
|
||
|
|
*
|
||
|
|
* This is the typical JavaDoc-style C-style "banner" comment. It starts with
|
||
|
|
* a forward slash followed by some number, n, of asterisks, where n > 2. It's
|
||
|
|
* written this way to be more "visible" to developers who are reading the
|
||
|
|
* source code.
|
||
|
|
*
|
||
|
|
* Often, developers are unaware that this is not (by default) a valid Doxygen
|
||
|
|
* comment block!
|
||
|
|
*
|
||
|
|
* However, as long as JAVADOC_BLOCK = YES is added to the Doxyfile, it will
|
||
|
|
* work as expected.
|
||
|
|
*
|
||
|
|
* This style of commenting behaves well with clang-format.
|
||
|
|
*
|
||
|
|
* @param theory Even if there is only one possible unified theory. it is just a
|
||
|
|
* set of rules and equations.
|
||
|
|
******************************************************************************/
|
||
|
|
void javadocBanner( int theory );
|
||
|
|
|
||
|
|
/***************************************************************************//**
|
||
|
|
* A brief history of Doxygen-style banner comments.
|
||
|
|
*
|
||
|
|
* This is a Doxygen-style C-style "banner" comment. It starts with a "normal"
|
||
|
|
* comment and is then converted to a "special" comment block near the end of
|
||
|
|
* the first line. It is written this way to be more "visible" to developers
|
||
|
|
* who are reading the source code.
|
||
|
|
* This style of commenting behaves poorly with clang-format.
|
||
|
|
*
|
||
|
|
* @param theory Even if there is only one possible unified theory. it is just a
|
||
|
|
* set of rules and equations.
|
||
|
|
******************************************************************************/
|
||
|
|
void doxygenBanner( int theory );
|
||
|
|
|