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上找到了一个问题和答案。不幸的是我不能再找到它了。我尝试了所有可以想象的搜索关键字变体而没有运气。所以我希望你们中的任何人都能找到副本。至少我的问题将通过为现有的Q＆amp; A提供不同措辞的“代理”来增加一些价值，从而提高未来访问者查找信息的几率。

更新

我想我最后通过使用不同的搜索引擎找到了另一个问题：Markdown for automatic doc generation?。似乎Doxygen支持Markdown。 Doxygen也支持C＃。但对于@Sam Harwell提到的要求，这可能不会有很长的路要走。

Answer 1

这个要点非常好：https://gist.github.com/formix/515d3d11ee7c1c252f92

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

Answer 2

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

Visual Studio将无法直接使用评论。在工作之前，需要通过Markdown处理器运行它们以生成格式正确的XML文档文件。这意味着您只能获得引用的项目的正确文档，而不能获取当前项目的文档。此外，如果您没有生成XML输出，那么您也不会产生其他开发人员在引用您的库时可以使用的任何输出。
Roslyn和SHFB项目都致力于改进对XML文档注释的IntelliSense支持。目前，SHFB专注于展示其自定义文档标记（例如<preliminary/>和<see langword="null"/>），而Roslyn专注于对cref属性值see和{的IntelliSense支持{1}}标签。据我所知，没有推动支持记录C＃代码的替代方法。

Answer 3

您可以使用Vsxmd（https://www.nuget.org/packages/vsxmd）。有关使用方法的更多详细信息，请参见软件包（https://github.com/lijunle/Vsxmd）的github页

Answer 4

Docfx

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

DocFX是.NET的API文档生成器，目前支持C＃和VB。它从源代码中的三斜杠注释中生成API参考文档。它还允许您使用Markdown文件来创建其他主题，例如教程和操作方法，以及自定义生成的参考文档

。

使用Markdown获取源代码文档

4 个答案: