c++ - 注释变量与 Doxygen 内联会带来任何惩罚吗？

Question

我看到大多数 Doxygen 文档对 C++ 函数的注释看起来类似于

/// a description of the function or method followed with comments, like so
/// @return true=success, false=error
/// @param[in] bar blah blah
/// @param[out] baz blah blah
/// @param[out] quux blah blah
/// @param[out] quuux blah blah
/// @param[out] quuuux blah blah
static bool foo_one( int *bar, int *baz, int *quux, int *quuux, int *quuuux );

或等效的 xml(大致)

/// a description of the function or method, followed by
/// <returns>true=success, false=error</returns>
/// <param name=bar>blah blah</param>
/// <param name=baz>blah blah</param>
/// <param name=quux>blah blah</param>
/// <param name=quuux>blah blah</param>
/// <param name=quuuux>blah blah</param>
static bool foo_two( int *bar, int *baz, int *quux, int *quuux, int *quuuux );

但我主要是像这样内联评论我的参数

/// a description of the function or method, followed by
/// @return true=success, false=error
static bool foo_three(
    int *bar,               ///< [in]  blah blah
    int *baz,               ///< [out] blah blah
    int *quux,              ///< [out] blah blah
    int *quuux,             ///< [out] blah blah
    int *quuuux             ///< [out] blah blah
);

所有这三个在 html 文件中给出相同的输出(除了中间那个，它没有指定输入/输出)。

我的问题:Doxygen、Visual Studio 或任何其他环境中是否存在我无法通过内联方法利用的功能？我知道在编写和阅读代码本身的注释时存在个人偏好，并且不想就这些进行辩论。我只想知道是否有 Doxygen 或其他环境功能或格式我会错过。

Answer 1

是的。

Doxygen 本身可以很好地处理内联注释。

但是，还要考虑源代码控制系统(例如git和git blame)记录历史的影响

使用内联注释，最后更改行的人就是添加或更改文档的人，这使得更难找到何时/为何更改代码本身。

在单独的行上注释，特别是如果在代码之后添加文档，检查历史记录以查找代码更改会更容易。