C# 带有 DoxyGen 的 Visual Studio 用于文档，还是应该使用其他东西？

Visual Studio with DoxyGen for documentation, or should we use something else?

提问by Deleted

We are currently using DoxyGen to document code written in C/C++, PHP and Java. To have a consistent environment it would be nice to use it for C# documentation as well.

我们目前正在使用 DoxyGen 来记录用 C/C++、PHP 和 Java 编写的代码。为了拥有一致的环境，最好也将其用于 C# 文档。

However we are wondering:

然而我们想知道：

• Do you see any advantages in the generated documentation layout or structure using something other than DoxyGen? We are generating documentation for external developers who are experienced with C# and the .NET platform. Maybe they are used to a certain documentation format?
• How well integrated can DoxyGen be with Visual Studio? Is there something which enables a one-click generation of documentation from inside the IDE?
• Is some other documentation system more integrated with Visual Studio?

• 您是否看到使用 DoxyGen 以外的其他工具生成的文档布局或结构有什么优势？我们正在为具有 C# 和 .NET 平台经验的外部开发人员生成文档。也许他们习惯于某种文档格式？
• DoxyGen 与 Visual Studio 的集成度如何？有没有什么东西可以从 IDE 内部一键生成文档？
• 其他一些文档系统是否与 Visual Studio 更加集成？

采纳答案by Christian

The default way of documenting C# code in Visual Studio is by XML documentation comments. In my opinion this is the best way to go for C# code because support for this is already integrated in Visual Studio (comment tag auto completion, warning about missing or incorrectly spelled parameters, ...). To document a method, just type three slashes (///) in front of the method body, and Visual Studio will insert an empty comment template for you to fill, like so:

在 Visual Studio 中记录 C# 代码的默认方式是通过XML 文档注释。在我看来，这是使用 C# 代码的最佳方式，因为对此的支持已经集成在 Visual Studio 中（注释标签自动完成、有关缺少或拼写错误的参数的警告，...）。要记录方法，只需///在方法主体前键入三个斜杠 ( )，Visual Studio 将插入一个空注释模板供您填写，如下所示：

/// <summary>
/// 
/// </summary>
/// <param name="bar"></param>
private void Foo(int bar)
{
    // ...
}

You can configure Visual Studio to generate an XML file from all the comments, which would then be fed into a documentation generator like Sandcastle. If you want to use Doxygen, this is no problem as it supports parsing XML comments.

您可以将 Visual Studio 配置为从所有注释生成一个 XML 文件，然后将其送入Sandcastle等文档生成器。如果你想使用Doxygen，这没有问题，因为它支持解析 XML 注释。

To sum up:I would recommend to use XML comments over special Doxygen comments for C# code. This way you have all the options. You can generate documentation in the standard Doxygen layout your organization is familiar with (becauses Doxygen supports XML comments) plus you have the option to generate documentation in a format known to .NET developers (with Sandcastle and Sandcastle Help FileBuilder).

总结一下：我建议在 C# 代码的特殊 Doxygen 注释上使用 XML 注释。这样你就有了所有的选择。您可以按照组织熟悉的标准 Doxygen 布局生成文档（因为 Doxygen 支持 XML 注释），此外您还可以选择以 .NET 开发人员已知的格式生成文档（使用 Sandcastle 和Sandcastle Help FileBuilder）。

Ah, and also try GhostDoc...

啊，还可以试试GhostDoc...

回答by Laurent Etiemble

Visual Studio does not have an integrated documentation system.

Visual Studio 没有集成的文档系统。

If you want to stay consistent with the other languages, you can try using Doxygen with the DoxycommentAddin for Visual Studio.

如果您想与其他语言保持一致，可以尝试将 Doxygen 与DoxycommentAddin for Visual Studio 结合使用。

For the C# or .NET documentation, several tools exists and the most used (to my knowledge) is Sandcastle.

对于 C# 或 .NET 文档，存在多种工具，最常用的（据我所知）是Sandcastle。

Finally, you can check this blog entrythat provides a small Python script that converts some C# specific tags into Doxygen ones.

最后，您可以查看此博客条目，该条目提供了一个小型 Python 脚本，可将一些 C# 特定标记转换为 Doxygen 标记。

回答by Jason Williams

There are several options for documentation:

文档有多种选择：

• The free Microsoft way. Use DocXml documentation comments, and then Sandcastle or a similar tool to build MSDN-style documentation. The advantage of this is that Visual Studio recognises the documentation (it syntax-colours the comments) and the documentation is instantly picked up by the Intellisense system (so if you hover your mouse pointer over a method you are calling, the tooltip will display the summary and parameter information that you entered in the Doc Comment)

• The free Doxygen system. This is easier to use and more flexible, but not supported by Visual Studio, so you lose the intellisense and syntax colouring advantages. On the plus side, Doxygen does parse the DocXml format, so you can get the best of both worlds by using the DocXml format with Doxygen to generate the external help.

• Commercial products like DocumentX, which allow you to edit the documentation in a WYSIWYG window.

• 免费的微软方式。使用 DocXml 文档注释，然后使用 Sandcastle 或类似工具来构建 MSDN 样式的文档。这样做的好处是 Visual Studio 可以识别文档（它对注释进行语法着色），并且智能感知系统会立即获取文档（因此，如果将鼠标指针悬停在正在调用的方法上，工具提示将显示您在文档注释中输入的摘要和参数信息）

• 免费的 Doxygen 系统。这更易于使用且更灵活，但不受 Visual Studio 支持，因此您失去了智能感知和语法着色优势。从好的方面来说，Doxygen 确实解析了 DocXml 格式，因此您可以通过将 DocXml 格式与 Doxygen 结合使用来生成外部帮助，从而获得两全其美的效果。

• DocumentX 等商业产品，允许您在 WYSIWYG 窗口中编辑文档。

I would recommend starting with DocXml comments and Doxygen to generate the external help, as that's the cheapest and easiest way to get started, and retains all the best features of VIsual Studio (intellisense etc).

我建议从 DocXml 注释和 Doxygen 开始生成外部帮助，因为这是最便宜和最简单的入门方法，并且保留了 VIsual Studio（智能感知等）的所有最佳功能。

I'd also suggest you look at my add-in, Atomineer Pro Documentation, which makes the generation and updating of DocXml, Doxygen, Qt or JavaDoc format comments much faster and easier within VS - an ideal complement to both Doxygen and Sandcastle.

我还建议您查看我的插件Atomineer Pro Documentation，它使 DocXml、Doxygen、Qt 或 JavaDoc 格式注释的生成和更新在 VS 中更快、更容易 - 是 Doxygen 和 Sandcastle 的理想补充。

回答by Peter Macej

.NET developers are used to MSDN-like documentation format used in VS help. Preferably directly integrated in VS help as it gives some bonus features like F1 help, filters, unified Index and TOC. Several tools were already mentioned. I would add one more commercial one-click solution, VSdocman.

.NET 开发人员习惯于 VS 帮助中使用的类似 MSDN 的文档格式。最好直接集成在 VS 帮助中，因为它提供了一些额外的功能，如 F1 帮助、过滤器、统一索引和 TOC。已经提到了几个工具。我会再添加一个商业的一键式解决方案，VSdocman。

XML doc comments are great because they are automatically used also in IntelliSense and Object Browser Quick Info.

XML 文档注释很棒，因为它们也会自动用于 IntelliSense 和对象浏览器快速信息。

回答by BlackStar

Doxygen can consume C# doc comments (///) just fine. Document your code as normal and run doxygen to scan them into standalone html, chm and pdf files. This is by far the most versatile, simple and non-invasive approach.

Doxygen 可以很好地使用 C# 文档注释 (///)。像往常一样记录您的代码并运行 doxygen 将它们扫描成独立的 html、chm 和 pdf 文件。这是迄今为止最通用、最简单和非侵入性的方法。

While doxygen isn't integrated into visual studio, it comes with a simple IDE and can scripted trivially as a custom external tool. Personally, I have integrated doxygen into my build scripts and it works flawlessly.

虽然 doxygen 没有集成到 Visual Studio 中，但它带有一个简单的 IDE，可以作为自定义外部工具轻松编写脚本。就个人而言，我已将 doxygen 集成到我的构建脚本中，并且它可以完美运行。

Finally, doxygen is cross-platform (which is an advantage if you ever find a need to port to Mono) and is significantly faster than SandCastle (both to setup and to run).

最后，doxygen 是跨平台的（如果您发现需要移植到 Mono，这是一个优势）并且比 SandCastle 快得多（设置和运行）。

This is an example of doxygen output for C# code on a ~1Mloc project: http://www.opentk.com/files/doc/annotated.html

这是 ~1Mloc 项目中 C# 代码的 doxygen 输出示例：http: //www.opentk.com/files/doc/annotated.html