与 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 或任何其他环境中是否有我无法通过内联方法使用的功能？我知道在编写和阅读代码本身的 cmets 时存在个人偏好，并且不想讨论这些。我只想知道是否有 Doxygen 或其他环境功能或我会错过的格式。

Answer 1

是的。

Doxygen 本身可以与内联 cmets 正常工作。

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

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

在单独的行中使用 cmets，尤其是在代码之后添加文档时，检查历史记录以查找代码更改更容易。