Using Markdown for source code documentation

Question

I am looking for an alternative to C#'s XML source code documentation which introduced by the very nature of XML a lot of noise that is heavy on the eye and more work to write:

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

Instead I would like to use Markdown for the documentation:

/// 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

I could bet I found a question and answer for exactly this on Stackoverflow before. Unfortunately I don't manage to find it anymore. I tried all variations of search keywords I could imagine without luck. So I hope that any of you will find the duplicate. At least my question will add some value to SO by providing a "proxy" to the existing Q&A with different wording, thus improving the odds for future visitors to find their information.

Update:

I guess I finally found the other question by using a different search engine: Markdown for automatic doc generation?. It seems that Doxygen supports Markdown. Doxygen supports C#, too. But this probably doesn't go a long way as for the requirements that @Sam Harwell mentioned.

Solution 1

This gist does the job pretty well: https://gist.github.com/formix/515d3d11ee7c1c252f92

The resulting doc looks like that: https://github.com/formix/MegaCityOne/blob/master/MegaCityOne/doc/api.md

Solution 2

Theoretically, your example could be used to provide proper documentation files for C# projects. However, I recommend you avoid this approach for the following reasons.

1. Visual Studio will not be able to consume the comments directly. They will need to be run through a Markdown processor to produce properly-formatted XML documentation files prior to working. This means you'll only ever be able to get proper documentation for referenced projects, and not for the current project. Also, if you aren't generating XML output, then you aren't producing any output other developers are able to use when they reference your library.

2. Both Roslyn and the SHFB project are working to improve IntelliSense support for XML documentation comments. At this time, SHFB focuses on showing its custom documentation tags (e.g. <preliminary/> and <see langword="null"/>), and Roslyn focuses on IntelliSense support for the cref attribute value of see and seealso tags. To my knowledge, there is no push for supporting an alternative method of documenting C# code.

Solution 3

Docfx

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

DocFX is an API documentation generator for .NET, which currently supports C# and VB. It generates API reference documentation from triple-slash comments in your source code. It also allows you to use Markdown files to create additional topics such as tutorials and how-tos, and to customize the generated reference documentation