使用Markdown获取源代码文档

本文关键字：文档 源代码 获取 Markdown 使用 | 更新日期: 2023-09-27 18:15:27

我正在寻找一种替代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增加一些价值，为现有的Q& a提供一个不同措辞的"代理"，从而提高未来访问者找到他们信息的几率。

更新:

我想我最终通过使用不同的搜索引擎找到了另一个问题:Markdown for自动文档生成?看来氧分子支持Markdown。氧也支持c#。但是对于@Sam Harwell提到的要求来说，这可能还不够。

使用Markdown获取源代码文档

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

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

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

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

  2. Roslyn和SHFB项目都在努力改进对XML文档注释的智能感知支持。此时，SHFB专注于显示其自定义文档标签(例如<preliminary/>和<see langword="null"/>)，而Roslyn专注于对see和seealso标签的cref属性值的智能感知支持。据我所知，目前还没有支持c#代码文档的替代方法。

Docfx

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

DocFX是一个用于。net 的API文档生成器，目前支持c#和VB。它从源代码中的三斜杠注释生成API参考文档。它还允许您使用Markdown文件创建其他主题，如教程和操作指南，并自定义生成的参考文档

您可以使用vsmd (https://www.nuget.org/packages/vsxmd)。关于如何使用的更多细节可以在github页面找到(https://github.com/lijunle/Vsxmd)

相关文章：