最兼容的C++ Doxygen注释，适用于IDE

Question

我一直在编写一些C++代码，其他与我合作的开发人员将使用这些代码。这里有很多MS（微软）开发人员（他们将Visual Studio作为主要IDE），我们也有很多开发人员为不同的项目使用其他IDE（如Eclipse和Qt，甚至一些使用XCode进行C++ Mac开发的人员）。

我拥有的代码是通用的库函数，可以跨平台兼容，因此将被不同平台/ IDE上的不同开发人员使用。这就带来了我的问题：是否有一种兼容的Doxygen注释“风格”，可以通过大多数流行的IDE（VS、Eclipse、Qt、Netbeans、XCode）的代码自动完成功能“理解”和使用？

如果没有“兼容”的方法，是否有任何插件可以用于所有IDE，以实现此功能，或者我必须编写自己的插件？谷歌搜索已经让我走了很多死胡同（可能是因为我可能没有正确输入我的问题），编写自己的插件是一个选项，但我更喜欢“兼容”的风格或现有的插件，如果可能的话，以节省时间。

提前感谢！

编辑1：我应该提到，我请求使用Doxygen样式的注释，因为它是我们用来构建一些文档的文档工具，因此我们制作的任何代码中的所有注释都必须是Doxygen样式（不确定为什么这个问题以前从未在这里出现，哈哈）。

- txtechhelp

---

如果你的IDE理解doxygen，那么它可能理解其中的所有内容。另一方面，如果它不理解，无论你使用什么语法，它都不会起作用。你遇到过任何特定的问题，比如IDE x不支持y吗？ - pezcode

@pezcode：Doxygen有很多注释代码的方式，主要是为了允许不同的注释模式工作。C#标准风格被接受（程度不同），JavaDoc风格也是如此。 - Nicol Bolas

@pezcode：不幸的是，正如Nicol所说，由于有许多注释代码的方式，Doxygen支持其中许多方式，因此这不是IDE x不支持y的问题，而更多地是为了我的其他开发人员使用语法糖。就像Nicol所说，例如支持C#样式，但只有在以C#项目为主项目运行的VisualStudio IDE中才被“识别”，因此如果我在XCode中运行C++项目，则无法工作（XCode可能不“理解”如何解析C#样式的注释，因此不会显示它）。 - txtechhelp

@pezcode：我更好奇是否有一种（或多种）注释代码的方法，以便许多不同的IDE可以“解析”这些注释，或者我是否需要为我知道正在使用的IDE编写插件来支持Doxygen“风格”的注释。 - txtechhelp

Answer 1

我一直在为这个问题苦苦挣扎。过去，我使用了几种不同的开发软件套件，每种套件都有其自己的怪癖，涉及使用文档来驱动一些更高级的功能。在使用C#（和Visual Studio 2010）开发项目后，我意识到XML注释似乎对我最有效。

我个人认为，这是大多数IDE应用程序本身的失败，例如，似乎Visual Studio仅支持XML注释用于C#应用程序以提供Intellisense等功能，以及不太花哨的语法突出显示。我发现在Visual Studio中有一个商业插件可用于“启用”此功能，但我为什么要为尚未启用的东西付费呢？

但是我已经偏离了你最初的问题。当我最初研究这个问题时，似乎苹果公司自己必须使用Doxygen，因为他们似乎已经使用了这个用于突出显示代码的标准。话虽如此，以下是一些其他资源，可以在其他应用程序中获得相同的功能：

• Atomineer Pro Documentation 看起来是适用于 Visual Studio 的工具，虽然我个人没有使用过它。它似乎相对简单易用。
• Eclox 看起来是一个基于 Eclipse 的前端插件，实际上使用了 Doxygen。但据我所记，你应该能够在 C++ 设置中调整 IDE 本身的语法高亮。
• Doxymacs 在 Emacs 中维护一个符号表，以便进行快速搜索。
• 看起来在 Vim 项目页面上也有一个脚本可以处理这个编辑器，它叫做 DoxygenToolkit。

我非常理解你的痛苦。每晚定期生成清晰文档并且易于搜索的标记语言确实让人感觉温暖舒适。最近，我一直在寻找可跨平台实现此目标的最佳机制。据我所知，大多数开发环境都支持各种扩展功能，而且由于Doxygen基本上是“黄金标准”，如果开发环境未能提供支持，通常也有办法强行引入。

如果你有兴趣，Doxygen实际上支持C# XML注释，但不幸的是我无法在Xcode中使其正常工作，而我自己没有足够熟练的AppleScript技能来进行hack。但如果你能做到，请务必更新！

- John Bellone

---

对于Intellisense，Visual Studio只需获取同一行上的任何注释（void foo() { // do stuff将在Intellisense工具提示中显示do stuff），或者在上面的行上的注释。它不需要任何特殊的语法。 - jalf

我记不得这在2008年是否有效，但它适用于2010年及更新版本，至少如此。 - jalf

http://msdn.microsoft.com/en-us/magazine/dd722812.aspx 似乎表明它将提供更好的结果。 - John Bellone

不是针对C++。我所描述的适用于C++，并且不需要任何特殊格式。 - jalf

抱歉回复晚了，但最终我选择了JavaDoc风格的注释...主要是因为在我维护的其他代码中更多地使用了这种风格。我想，将来有时间的话，我会编写一些插件，以便流行的IDE可以更好地处理XML/Doxygen风格的注释。 - txtechhelp