自定义 Doxygen html 输出答案

【问题标题】：Customizing Doxygen html output自定义 Doxygen html 输出
【发布时间】：2011-05-28 12:05:03
【问题描述】：

我们有一个必须遵循的函数头格式。基本上是这样的

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

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

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

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

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

【问题讨论】：

标签： c comments doxygen

【解决方案1】：

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

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

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

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

注意\param <type> <name> 不是正确的 Doxygen 语法；它是\param <name> <description>。 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 ) ;

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

【讨论】：

我会看看这是否可行，但可能会涉及太多的文书工作（这是为了飞行值得的代码），我相信他们会争辩说他们希望它在没有任何有关 Doxygen 的知识。当然，我认为任何能够理解来源的人都应该能够推断出 Doxygen 标签所代表的内容。
@Andy：虽然我认为编码标准很重要，但不幸的是，您现有的标准设计得如此糟糕（通过复制隐含的信息，至少在您的示例中没有提供任何实际有用的信息）已经在代码中）。从长远来看，改变它会更好。当然，您必须考虑如何处理所有遗留代码 - 更改它或提出让步。如果始终如一地应用，可以通过脚本对其进行更改。
实际上能够说服他们重组函数头！我们使用的是 xml 格式的 cmets，因此我们可以在必要时使用其他第三方工具解析信息
@Andy：有趣；你知道 Visual Studio 已经为文档定义了 XML 注释格式吗？可能值得使用他们的标签：msdn.microsoft.com/en-us/magazine/cc302121.aspx。然而，XML 的问题当然是 "尖括号税" (codinghorror.com/blog/2008/05/xml-the-angle-bracket-tax.html)
是的，我确实使用了 Visual Studio 定义的大部分标签。 Doxygen 吸收了其中的大部分。我们确实失去了一些可读性，但我觉得利大于弊。