documentation - 将内部库的 doxygen 注释 block 放在 H 或 CPP 文件中的哪里？

Question

常识告诉我们，Doxygen 注释 block 必须放在类、结构、枚举、函数、声明所在的头文件中。我同意，对于一个库来说，这是一个合理的论据，该库应该在没有源代码的情况下进行分发(只有 header 和带有目标代码的库)。

但是......当我开发公司内部(或作为我自己的业余项目)库时，我一直在考虑完全相反的方法，该库将与其完整源代码一起使用。我的建议是将大的注释 block 放在实现文件(HPP、INL、CPP 等)中，以免混淆 header 中声明的类和函数的接口(interface)。

优点:

• 减少头文件中的困惑，仅可以添加函数的分类。
• 例如，使用 Intellisense 时预览的注释 block 不会发生冲突 - 这是我在 .H 文件中有一个函数的注释 block 并且在同一文件中具有其内联定义时观察到的缺陷.H 文件，但包含在 .INL 文件中。

缺点:

• (显而易见)注释 block 不在声明所在的头文件中。

那么，您有什么想法和可能的建议？

Answer 1

我喜欢利用名称可以记录在多个位置的事实。

在头文件中，我编写了该方法的简要描述，并记录了其所有参数 - 这些参数比方法本身的实现更不可能更改，如果更改，则需要更改函数原型(prototype)无论如何。

我将长格式文档放在实际实现旁边的源文件中，这样细节就可以随着方法的发展而改变。

例如:

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