Question

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

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

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

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

当Doxygen生成html注释时，它会添加Parameters标题。我们需要有第4行，所以这会创建两行代表参数的文档，第一行来自第4行，第二行来自Doxygen自动插入。

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

Answer 1

简单的解决方案是完全删除“参数：”文本;它完全是多余的，因为Doxygen标记使它们非常清楚它们是参数！

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

如果您必须尝试将现有格式与Doxygen兼容格式混合使用，那么使用C ++ / C99行注释会更容易，而不是阻止注释;大多数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 html输出

1 个答案: