功能组的文档注释

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);

这会复制简要说明并插入完整文档功能的链接，但它要求用户点击链接并查看哪些参数是相关的。

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

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