使用Doxygen为已存在的C#代码创建带有XML注释的文档

Question

我已经到处都看到了，Doxygen是为C#代码生成文档的最佳选择。我要先记录下单个接口（踏出第一步），它已经有了XML注释（///）。

由于有大量帖子和信息可用（包括doxygen.org）表明这些注释已被支持，当我运行doxywizard时，我会收到“警告：未记录复合公司::产品::我的接口”等错误信息，让我相信我可能误解了XML文档（但愿没有，根据MSDN我在谈论正确的事情），或者我已经误配置了doxywizard。

我首先通过向导选项卡运行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

---

Dave，你在声明接口的那一行上面有注释吗？ - Eric Farr

@Eric 是的，我更新了我的问题以显示评论。也许我需要一些特殊的doxygen语法？ - Dave

嗯...看起来一切都很好。我能想到的就是有一堆EXTRACT_参数。尝试将它们全部设为YES。你想做的事情会成功的，只是缺少了一些东西。使用doxygen还需要更多的试错。 - Eric Farr

@Eric 哈哈，时机正好！我刚刚在读有关EXTRACT_ALL的文章后发布了这篇文章。启用它使它工作了，尽管我觉得即使禁用该设置，它也应该能够工作。感谢您的评论。 - Dave

Answer 1

我想我明白了。Doxygen手册说，EXTRACT_ALL = 0是默认设置，在这种情况下，“只生成有文档的成员、文件、类和命名空间的文档”。现在，我认为我已经正确地记录了它们，但显然不是这样。我刚刚启用了EXTRACT_ALL，警告消失了，而且我获得了接口的文档！我研究了“特殊文档块”，以为我漏掉了什么（感谢Eric Farr的评论），但它没有提到需要对C#代码执行任何特殊操作，因此我认为EXTRACT_ALL的默认值仍应该起作用。

- Dave

---

很高兴你找到了它。Doxygen有时可能会让人沮丧，但对于你想要做的事情来说，它是最好的免费工具。 - Eric Farr