使用Markdown获取源代码文档

Question

我正在寻找C#的XML源代码文档的替代方案,该文档根据XML的本质介绍了很多噪声,这些噪声在眼睛上很重要并且需要编写更多工作:

/// <summary>
/// This is text of importance. Linking to
/// <see cref="AnotherClass>is somewhat verbose.</see>
/// </summary>
/// <param name="andSo">is parameter documentation</param>

相反,我想使用Markdown作为文档:

/// This is text of importance. Linking to [an](OtherClass) is less verbose.
/// 
/// Empty lines would make a new paragraph
///
/// aParameter
/// :    could possibly be documented in definition-list manner
///      as in http://bit.ly/1l9ik26

我敢打赌我之前在Stackoverflow上找到了一个问题和答案.不幸的是我不能再找到它了.我尝试了所有可以想象的搜索关键字变体而没有运气.所以我希望你们中的任何人都能找到副本.至少我的问题将通过为现有问答提供不同措辞的"代理"来增加一些价值,从而提高未来访问者查找信息的几率.

更新:

我想我终于通过使用不同的搜索引擎找到了另一个问题:Markdown用于自动生成doc？.似乎Doxygen支持Markdown.Doxygen也支持C#.但对于@Sam Harwell提到的要求,这可能不会有很长的路要走.

Answer 1

从理论上讲，您的示例可用于为 C# 项目提供适当的文档文件。但是，出于以下原因，我建议您避免使用这种方法。

1. Visual Studio 将无法直接使用注释。在工作之前，它们需要通过 Markdown 处理器运行以生成格式正确的 XML 文档文件。这意味着您将永远只能获得引用项目的正确文档，而不是当前项目的文档。此外，如果您不生成 XML 输出，那么您不会生成其他开发人员在引用您的库时能够使用的任何输出。

2. Roslyn 和 SHFB 项目都在努力改进对 XML 文档注释的 IntelliSense 支持。此时，SHFB 侧重于展示其自定义文档标签（例如<preliminary/>和<see langword="null"/>），而 Roslyn 侧重于cref对see和seealso标签的属性值的IntelliSense 支持。据我所知，并没有推动支持记录 C# 代码的替代方法。

Answer 2

这个要点做得很好:https://gist.github.com/formix/515d3d11ee7c1c252f92

生成的文档如下所示:https://github.com/formix/MegaCityOne/blob/master/MegaCityOne/doc/api.md