1

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
tstenner
  • 10,080
  • 10
  • 57
  • 92

1 Answers1

1

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.

albert
  • 8,285
  • 3
  • 19
  • 32
  • That's a great idea. Let me follow up with my next question "How do I sort a C header file by reversed function names" ;-) – tstenner Aug 20 '19 at 12:48
  • Please don't pose new questions in comments but make a new question out of it! Just give an example with what you want (is not 100% clear from such a small comment). – albert Aug 20 '19 at 12:50
  • It was mostly joking, but since it might be useful to others: I reordered the functions by grepping for `foo_\w\+(`, `foo_\w\+1(` etc. and then copying the block. – tstenner Aug 20 '19 at 12:53
  • I've improved your answer by grouping the functions with `@{` so I can document `foo_` for all types at once – tstenner Aug 20 '19 at 12:58
  • For the reverse order: How do you mean, just seeing to it that int3 is the first function in the file, int2 the second and in the third? Don't forget to set `SORT_MEMBER_DOCS=NO` as this is by default set to `YES` – albert Aug 20 '19 at 12:59
  • I originally had it ordered as `foo_int`, `foo_int2`, `foo_int3`, `foo_float`, `foo_float2` etc. for 8 types and up to four parameters, so sorting by function name wouldn't work, but sorting by reversed function names (`foo_int3`, `foo_float3`, …) would've helped – tstenner Aug 20 '19 at 13:01
  • out of the box sorting won't work as sorters will not look just at the numbers but also what is in front of it , so it will all `int..` together and all`float..` together. – albert Aug 20 '19 at 13:04