CODEWITHSUNDEEP
c++doxygendocumentation-generation
tstenner
tstenner

Reputation: 10291

Documentation comments for function groups

I want to generate an API documentation with Doxygen.

As it's a C API, I can have neither default arguments nor templates, so the straightforward

/** @brief foo
 * Do the foo
 * @param typed A typed parameter
 * @param bar Optional parameter 1
 * @param baz Another optional parameter
 */
template<typename T> void foo(T typed, bool bar=true, bool baz=true);

becomes

/** @brief foo
 * Do the foo
 * @param typed A typed parameter
 * @param bar Optional parameter 1
 * @param baz Another optional parameter
 * @{
 */
void foo_int(int typed);
void foo_int2(int typed, bool bar);
void foo_int3(int typed, bool bar, bool baz);
void foo_float(float typed);
void foo_float2(float typed, bool bar);
void foo_float3(float typed, bool bar, bool baz);
///@}
// and so on

With the group (@{/@}) the documentation and parameters are applied to all functions, but for each optional parameter and function (bar and baz) I get a warning.

The next approach involves @copydoc:

/** @brief foo
 * Do the foo
 * @param typed A typed parameter
 * @param bar Optional parameter 1
 * @param baz Another optional parameter
 */
void foo_int3(int typed, bool bar, bool baz);
/// @copybrief foo_int3 @sa foo_int3
void foo_int(int typed);
/// @copybrief foo_int3 @sa foo_int3
void foo_int2(int typed, bool bar);
/// @copybrief foo_int3 @sa foo_int3
void foo_float(float typed);
/// @copybrief foo_int3 @sa foo_int3
void foo_float2(float typed, bool bar);
/// @copybrief foo_int3 @sa foo_int3
void foo_float3(float typed, bool bar, bool baz);

This copies the brief description and inserts a link to the fully documented function, but it requires the user to follow the link and see which parameters are relevant.

Ideally, I want something like:

/** @brief foo
 * @param typed A typed parameter
 * @optparam bar A parameter that's documented if it's actually in the function signature
 */

The minimal doxygen configuration is as follows:

# Doxyfile 1.8.13
DOXYFILE_ENCODING      = UTF-8
PROJECT_NAME           = doxygen_mwe
DISTRIBUTE_GROUP_DOC   = YES
EXTRACT_ALL            = YES
INPUT                  = ./
FILE_PATTERNS          = *.h

Upvotes: 1

Views: 452

Answers (1)

albert
albert

Reputation: 9057

You start with the most complex version why not start with the easiest version and add the other parameters as required?

Like:

/** @brief foo
 * Do the foo
 * @param typed A typed parameter
 * @{
 */
void foo_int(int typed);
void foo_float(int typed);
/// @}
/** @copydoc foo_int
 * @param bar Optional parameter 1
 * @{
 */
void foo_int2(int typed, bool bar);
void foo_float2(int typed, bool bar);
/// @}
/** @copydoc foo_int2
 * @param baz Another optional parameter
 * @{
 */
void foo_int3(int typed, bool bar, bool baz);
void foo_float3(int typed, bool bar, bool baz);
/// @}

When using this construct with groups @{...@} don't forget to set DISTRIBUTE_GROUP_DOC=YES.

Upvotes: 1

Related Questions