Where to put the doxygen comment blocks for an internal library - in H or in CPP files?

小开

标题: 更容易阅读的评论，因为有较少的其他“噪音”时，看文件。

来源: 然后，在查看注释时就可以阅读实际的函数。

我们只使用标题中注释的所有全局函数和源代码中注释的本地函数。如果需要，您还可以包含 copiddoc 命令，以便在多个位置插入文档，而不必多次编写(对于维护更好)

You could however also get the results copied over to different file documentation with a simple command. E.g. :-

我的档案

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

我的档案1.c

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

现在您可以获得关于这两个函数的相同文档。

这样可以减少代码文件中的噪音，同时可以在最终输出中的几个位置显示在一个位置上编写的文档。

小开

通常我把接口(param，return)的文档放在。H 文件和实施的文档(详细信息)。转交。Cpp/.M 档案。Dox 将函数/方法文档中的所有内容进行分组。

小开

我把所有东西都放在头文件里了。

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

小开

在标题中包含注释意味着，如果注释发生更改，则必须重新编译类的所有用户。对于一个大型项目来说，如果程序员冒险花费20分钟重建所有东西，他们将不太愿意更新头部的注释。

还有。.因为您应该阅读 html 文档，而不是浏览文档代码，所以在源文件中找到注释块并不是一个大问题。

小开

最佳答案

把文档放在人们可以阅读和编写的地方，因为他们正在使用和编写代码。

Class comments go in front of classes, method comments in front of methods.

这是确保维护的最好方法。它还使您的头文件相对精简，并避免了人们更新方法文档的 touching问题，从而导致头文件变脏并触发重新构建。我实际上知道人们用它作为编写文档 回见！的借口

小开

我喜欢利用这样一个事实，即姓名可以在多个地方进行记录。

在头文件中，我写了一个方法的简短描述，并记录了它的所有参数——这些参数比方法本身的实现更不可能改变，如果它们改变了，那么无论如何都需要改变函数原型。

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

例如:

我的模块

/// @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;
}

小开

我在用 QtCreator 编程。一个非常有用的技巧包括 Ctrl-Click on a function or method 以获得头文件中的声明。

当该方法在头文件中被注释时，可以快速找到要查找的信息。因此，对我来说，注释应该位于头文件！

小开

在 c + + 中，有时候实现可以在头和。Cpp 模块。在这里，将文档放到头文件中似乎更为简单，因为头文件是保证所有公共函数和方法的唯一位置。