注释变量与 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 文件中给出相同的输出（除了中间那个，它没有指定 in/out）。

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

Answer 1

是的。

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

但是，还要考虑源码控制系统对历史记录的影响（例如git，git blame）

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

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

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

Does commenting variables inline with Doxygen come with any penalties?

c++

doxygen