C 自定义Doxygen html输出

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

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

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

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

当Doxygen生成html注释时，它会添加参数标题。我们需要有第4行，因此这将创建带有两行的文档，其中一行表示参数，第一行来自第4行，第二行是Doxygen自动插入

---

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

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

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

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

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

注意

\param

不是正确的Doxygen语法；它是

\param

。Doxygen从代码中获取类型；同样，在注释中指定类型完全是多余的，这也是另一个维护难题

我强烈建议您使用一个更强氧和维护友好的功能锅炉板。我使用以下基本形式（无论其价值如何）：

---

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

我想看看这是否可行，但可能会涉及太多的文书工作（这是为了飞行代码），我相信他们会争辩说，他们希望它在不了解强氧的情况下可读。当然，我认为任何能够理解源代码的人都应该能够推断出Doxygen标签代表的是什么。@Andy：虽然我认为编码标准很重要，但不幸的是，您现有的标准设计得太差了（通过复制隐含的信息，至少在您的示例中，没有提供代码中没有的实际有用信息）当然，从长远来看，改变它将是更好的，IMO.必须考虑如何处理所有遗留代码——改变它或提出让步。如果应用一致，改变它可以是脚本编写的。实际上，可以将其转换成函数头。我们使用XML格式的注释，这样我们就可以使用PAR。如果需要，请使用其他第三方工具将信息发送到necessary@Andy：有趣；您知道Visual Studio已经为文档定义了XML注释格式吗？可能值得使用它们的标记：。但是XML的问题当然是“角度括号税”（）是的，我确实使用了VisualStudio定义的大多数标记。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 ) ;