使用 doxygen 为带有 XML 注释的现有 C# 代码创建文档答案

【问题标题】：Using doxygen to create documentation for existing C# code with XML comments使用 doxygen 为带有 XML 注释的现有 C# 代码创建文档
【发布时间】：2011-11-07 14:35:41
【问题描述】：

我已经到处阅读 doxygen 是为 C# 代码生成文档的方法。我有一个我想首先记录的界面（小步骤），并且它已经存在 XML cmets (///)。

由于大量帖子和可用信息（包括 doxygen.org）表明这些 cmets 已受支持，我很惊讶当我运行 doxywizard 时，我收到类似“警告：Compound Company::Product: :MyInterface 没有记录”。

这让我相信我以某种方式误解了 XML 文档（希望不是，根据 MSDN 我说的是正确的事情），或者我错误地配置了 doxywizard。

我首先通过 Wizard 选项卡运行 doxywizard，并指定我要支持 C#/Java。当我运行它时，我的 HTML 页面是空白的，大概是因为前面提到的警告。然后我尝试通过专家选项卡指定单个文件并再次运行——同样的行为。

谁能告诉我我缺少什么开关或设置来让 doxygen 生成 HTML？

以下是我的界面中记录的属性/方法的示例：

/// <summary>
/// Retrieve the version of the device
/// </summary>
String Version { get; }

/// <summary>
/// Does something cool or really cool
/// </summary>
/// <param name="thing">0 = something cool, 1 = something really cool</param>
void DoSomething( Int32 thing);

我在界面上方确实有注释，像这样：

/// <summary>
/// MyInterface
/// </summary>
public interface MyInterface {...}

【问题讨论】：

Dave，你在声明接口的那一行上面有注释吗？
@Eric 是的，我愿意...我已经更新了我的问题以显示评论。也许我需要一些特殊的 doxygen 语法？
嗯....一切看起来都很好。我能想到的就是有一堆 EXTRACT_ 参数。尝试将它们全部变为“是”。您正在尝试做的事情会奏效。只是缺少一些东西。我想要对 doygen 进行更多的反复试验。
@Eric 哈哈，好时机！在阅读了一些关于 EXTRACT_ALL 的内容后，我刚刚发布了这个消息。启用它使其工作，尽管我觉得即使禁用该设置它也应该工作。谢谢你们的cmets。

标签： c# documentation doxygen xml-documentation

【解决方案1】：

我想我已经明白了。 doxygen 手册说 EXTRACT_ALL = 0 是默认设置，在这种情况下“只会为记录的成员、文件、类和命名空间生成文档”。现在，我认为我已经正确地记录了它们，但显然不是。我刚刚启用了 EXTRACT_ALL，警告就消失了，我得到了我的界面的文档！我阅读了“特殊文档块”，认为我遗漏了一些东西（感谢 Eric Farr 的评论），但它没有提到为 C# 代码做任何特殊的事情，所以我假设 EXTRACT_ALL 的默认值应该仍然有效。

【讨论】：

很高兴你找到了它。 Doxygen 有时会令人沮丧，但它是您想做的最好的免费工具。