在哪里放置doxygen注释块用于内部库 - 在H或CPP文件中？

Question

常识告诉Doxygen注释块必须放在头文件中,其中包含类,结构,枚举,函数和声明.我同意这是一个合理的论据,这些库意味着在没有源的情况下进行分发(只有头和带有目标代码的库).

但是......当我正在开发一个公司内部(或者作为我自己的副项目)库时,我一直在考虑完全相反的方法,该库将与其完整的源代码一起使用.我建议将大的注释块放在实现文件(HPP,INL,CPP等)中,以免混乱标题中声明的类和函数的接口.

优点:

• 头文件中的杂乱性较小,只能添加功能分类.
• 使用Intellisense时预览的注释块不会发生冲突 - 这是我在.H文件中有一个函数的注释块并在同一.H文件中使用其内联定义时观察到的一个缺陷但包含在.INL文件中.

缺点:

• (显而易见的一个)注释块不在声明所在的头文件中.

那么,您的想法和建议是什么？

Answer 1

将文档放在人们将要阅读的地方,并在他们使用和编写代码时编写它.

类注释放在类前面,方法注释放在方法前面.

这是确保维护事物的最佳方法.它还可以使您的头文件保持相对精简,并避免人们更新方法文档时导致标题变脏并触发重建的触摸问题.我实际上已经知道人们将其作为后来编写文档的借口!

Answer 2

我喜欢利用名称可以在多个地方记录的事实.

在头文件中,我写了一个方法的简短描述,并记录了它的所有参数 - 这些参数不太可能比方法本身的实现更改,如果它们这样做,那么在任何情况下都需要更改函数原型.

我将长格式文档放在实际实现旁边的源文件中,因此可以随着方法的发展更改细节.

例如:

mymodule.h

/// @brief This method adds two integers.
/// @param a First integer to add.
/// @param b Second integer to add.
/// @return The sum of both parameters.
int add(int a, int b);

mymodule.cpp

/// This method uses a little-known variant of integer addition known as
/// Sophocles' Scissors. It optimises the function's performance on many
/// platforms that we may or may not choose to target in the future.
/// @TODO make sure I implemented the algorithm correctly with some unit tests.
int add(int a, int b) {
  return b + a;
}

Answer 3

在标题中有注释意味着如果注释被更改,则必须重新编译类的所有用户.对于大型项目,编码人员如果冒险在接下来的20分钟内重建所有内容,则不太愿意更新标题中的评论.

并且..因为您应该阅读html文档而不是浏览文档的代码,所以注释块在源文件中更难找到并不是一个大问题.

Answer 4

标题: 更容易阅读评论,因为查看文件时其他"噪音"较少.

来源: 然后在查看评论时,您可以使用实际的功能进行阅读.

我们只使用在源代码中注释的头文件和本地函数中注释的所有全局函数.如果需要,还可以包含copydoc命令,将文档插入多个位置,而不必多次写入(更好的维护)

但是,您也可以使用简单的命令将结果复制到不同的文件文档中.例如: -

我的file1.h

/**
 * \brief Short about function
 *
 * More about function
 */
WORD my_fync1(BYTE*);

我的file1.c

/** \copydoc my_func1 */
WORD my_fync1(BYTE* data){/*code*/}

现在,您将获得有关这两个函数的相同文档.

这样可以减少代码文件中的噪音,同时将文档写入最终输出中多个位置的文档中.