使用Doxygen在代码中注释变量会有任何影响吗？

Question

使用Doxygen在代码中注释变量会有任何影响吗？

6

我看到大多数用于注释C++函数的Doxygen文档都类似于：

/// 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或其他环境功能或格式感兴趣。

- buttonsrtoys

你说的“罚款”是什么意思？文档是否已经呈现得很好了？如果是这样，你还在烦恼什么？ - πάντα ῥεῖ

你可能想在其中一个Doxygen论坛上提问。 - Thomas Matthews

@πάντα ῥεῖ，不冒犯，但是我想问一下，使用Doxygen、Visual Studio或其他任何环境时，是否有我无法利用的功能？我对输出的外观感到满意，但我的公司正在注释大量的旧代码，如果XML或其他技术具有我不知道的功能，而我的方法无法利用它们，我不想引导他们使用我的技术。 - buttonsrtoys

@buttonsrtoys 我还是不明白你现在想要什么。你使用doxygen或其他工具吗？ - πάντα ῥεῖ

1个回答

网页内容由stack overflow 提供, 点击上面的

可以查看英文原文，
原文链接

- Marc Alff · Accepted Answer

是的。

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

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

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

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