功能组的文档注释

Question

我想用 Doxygen 生成一个 API 文档。

因为它是 C API，我既不能没有默认参数也不能有模板，所以直截了当

/** @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);

变成

/** @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

对于组 (@{/@})，文档和参数适用于所有函数，但对于每个可选参数和函数（bar 和 baz ) 我收到警告。

下一个方法涉及 @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);

这会复制简要说明并在完整记录的函数中插入 link，但它需要用户遵循 link 并查看哪些参数是相关的。

理想情况下，我想要这样的东西：

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

最小doxygen配置如下：

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

Answer 1

您从最复杂的版本开始为什么不从最简单的版本开始并根据需要添加其他参数？

喜欢：

/** @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);
/// @}

将此构造与组 @{...@} 一起使用时，请不要忘记设置 DISTRIBUTE_GROUP_DOC=YES。

功能组的文档注释

Documentation comments for function groups

c++

doxygen

documentation-generation