If you haven’t used Doxygen or a similar documentation generator, start using it. If there’s something worse than bad code is bad or uncommented code. Doxygen is so easy to use that there’s really no excuse. There is one exception: there’s not always easy examples of how to use it and nothing really practical. Here’s my attempt at correcting that mistake:
/** \defgroup Example Example
* @{
*/
/*!
* \brief Sample Function that’s commented
*
* This is an extended description about the function
*
* \par More information here is in bold and indented
*
* @param param1 is the first parameter
* @param param2 is the second parameter
*
* \return 0 if successful, 1 if failed.
*
* \par Example Usage:
* doxyFunctionExample1(1, 1);
*/
int doxyFunctionExample1(int param1, int param2)
{
return 0;
}
/** @}*/
I apologize for the formatting. Using the template above you get the following results:
The example contains a lot of details left out in many Doxygen tutorials/docs and should cover most cases. You can use the \par to create a custom paragraph, such as the example usage one above.