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命令，将文档插入多个位置，而不必多次写入（更好地进行维护）

然而，您也可以使用简单的命令将结果复制到不同的文件文档中。例如。： -

我的文件1.h

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

我的文件1.c

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

现在，您可以获得有关这两个功能的相同文档。

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

Answer 5

通常我将.h文件中的接口（\ param，\ return）文档和.c / .cpp / .m文件中的实现文档（\ details）放在一起。 Doxygen将功能/方法文档中的所有内容分组。

Answer 6

我把所有内容放在头文件中。

我记录了所有内容，但通常只提取公共界面。

Answer 7

我正在使用QtCreator进行编程。一个非常有用的技巧包括Ctrl-单击一个函数或方法来获取头文件中的声明。

在头文件中注释方法后，您可以快速找到要查找的信息。所以对我来说，评论应该位于头文件中！

Answer 8

在c ++中，有时可以在头文件和.cpp模块之间拆分实现。将文档放入头文件似乎更简洁，因为这是唯一保证所有公共函数和方法的地方。

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

8 个答案: