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

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

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

优点:

头文件中的杂乱性较小,只能添加功能分类.

使用Intellisense时预览的注释块不会发生冲突 - 这是我在.H文件中有一个函数的注释块并在同一.H文件中使用其内联定义时观察到的一个缺陷但包含在.INL文件中.

缺点:

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

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

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

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

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

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

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

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

例如:

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);

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

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

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