自定义 Doxygen html 输出

Question

我们有一个必须遵循的函数头格式。它基本上看起来像这样

/**
* Name: blah
*
* Parameters:
*       int foo
*       bool bar
*
* .....

我们正在尝试使用 doxygen 生成一些文档，但一个问题是，当我们将代码更改为：

/**
* Name: blah
*
* Parameters:
*  \param  int foo
*  \param  bool bar
*
* .....

当 Doxygen 生成 html 注释时，它会添加参数标题。我们需要第 4 行，因此这会创建包含 2 行参数的文档，第一行来自第 4 行，第二行来自 Doxygen 自动插入。

我希望我能做的是要么让 Doxygen 忽略第 4 行，要么添加让它不插入它自己的“参数：”标题。有人知道这是否可能吗？

Answer 1

简单的解决方案是完全删除“Parameters:”文本；它完全是多余的，因为 Doxygen 标记非常清楚地表明它们是参数！

就此而言，“名称：”标签也是完全多余的，它迫使您将名称放在注释和代码中。你为什么需要那个？它的名字就在代码中。这是一个不必要的注释维护难题，Doxygen 将在代码中使用名称，而不是生成的文档中注释中的名称。

如果您必须尝试将现有格式与 Doxygen 兼容格式混合，那么使用 C++/C99 行注释而不是块注释会更容易；大多数 C 编译器都支持它们：

// Name: blah
//
// Parameters:
/// \param  foo Description of foo
/// \param  bar Description of bar

注意 \param; 不是正确的 Doxygen 语法；它是 \param; <描述>。 Doxygen 从代码中获取类型；再次在注释中指定类型完全是多余的，并且是另一个维护难题。

我强烈建议您完全使用 Doxygen 和维护友好的功能样板。我使用以下基本形式（就其价值而言）：

//! @brief  Brief description
//!
//! Full description if necessary.
//! @param p1    p1 description
//! @param p2    p2 description
//! @return Return value description
int foobar( int p1, int p2 ) ;

显然，无论您使用 /// 还是 //！ \ 或@ 是一个偏好问题。