使用 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上找到了一个关于这个问题的问答，但不幸的是我找不到它了。我尝试了所有能想象到的搜索关键词的各种变化，但都没有成功。所以我希望你们中的任何一个能够找到重复的内容。至少我的问题将通过提供与现有问答不同措辞的“代理”，为SO增加一些价值，从而提高未来访问者找到信息的几率。

更新：

我想我最终通过使用不同的搜索引擎找到了另一个问题：自动生成文档的Markdown？。看起来Doxygen支持Markdown。Doxygen也支持C#。但这可能无法满足@Sam Harwell提出的要求。

- chiccodoro

Answer 1

这个代码片段可以很好地完成任务：https://gist.github.com/formix/515d3d11ee7c1c252f92 生成的文档看起来像这样：https://github.com/formix/MegaCityOne/blob/master/MegaCityOne/doc/api.md。

- formixian

---

您IP地址为143.198.54.68，由于运营成本限制，当前对于免费用户的使用频率限制为每个IP每72小时10次对话，如需解除限制，请点击左下角设置图标按钮（手机用户先点击左上角菜单按钮）。 - chiccodoro

但是Markdown关注格式化文本，而文档化代码需要一种语法来将文档元素与类或方法的参数、异常、备注等相关联，或者添加过期标记。 - formixian

您添加的链接是关于简化的文档语法，与Markdown无关。不过，您的问题是合理的：您想要一个可以在文档元素中理解Markdown的简化文档语法。好吧...我不知道有任何可以做到这一点的解析器...我会研究您在更新中发布的链接的;o) - formixian

在记录代码时，需要一种语法来将文档元素与代码相关联...当然，在我的原始问题中，我包含了一个关于如何实现这一点的想法 :-) 这并不需要XML。Java有自己的Javadoc语法，可以使用更少的“噪音”。Markdown会更好。 - chiccodoro

Answer 2

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

1. Visual Studio无法直接使用这些注释。它们需要通过Markdown处理器运行，以生成适当格式的XML文档文件，然后才能使用。这意味着你只能获取已引用项目的正式文档，而不能获取当前项目的正式文档。此外，如果您没有生成XML输出，则不会生成其他开发人员在引用库时能够使用的任何输出。
2. Roslyn和SHFB项目都在努力改进XML文档注释的智能感知支持。目前，SHFB专注于显示其自定义文档标记（例如和），而Roslyn专注于支持see和seealso标记的cref属性值的智能感知支持。据我所知，没有推动支持一种替代的C#代码文档化方法。

- Sam Harwell

---

广告1，我知道这一点。然而，我发现至少对于摘要文本，如果省略summary元素，在IntelliSense中显示效果也很好。至于其他方面，我希望有（或将来会有）支持该类型文档的Visual Studio扩展。广告1b（为了供其他人引用库的文档）：是的。需要另一个工具，从内联文档生成正确的XML文件。广告2. ...这真是太遗憾了。 - chiccodoro

尽管想使用Markdown，但Sandcastle Help File Builder非常棒。此外，如果我没记错的话，Scott Gu几年前演示了一个Visual Studio扩展程序，利用WPF编辑器渲染来自动显示代码注释，就像在文档查看器中查看时一样。我认为这从未被公开，但它将大大解决这个问题。 - Daniel

Answer 3

Docfx。

https://dotnet.github.io/docfx/tutorial/docfx_getting_started.html

DocFX是.NET的API文档生成器，目前支持C#和VB。它可以从源代码中的三斜杠注释中生成API参考文档。它还允许您使用Markdown文件创建额外的主题，如教程和操作说明，并自定义生成的参考文档。

- JohnFI

Answer 4

你可以使用 Vsxmd（https://www.nuget.org/packages/vsxmd）。有关如何使用的更多详细信息，请查看该软件包的Github页面（https://github.com/lijunle/Vsxmd）。

- Sales Lopes