29

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.

Improve this question
0

4 Answers 4

Reset to default
8

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

Improve this answer
Sign up to request clarification or add additional context in comments.

4 Comments

Your link looks interesting. However it does not exactly the same as what I intended: It extracts normal XML documentation and produced markdown. I was looking for a tool that extracts markdown from the source code, so I could document the code with markdown rather than XML.
But Markdown is about formatting text, while documenting code needs a syntax to relate documentation elements to a class or method's parameters, exceptions, remarks etc. or to add deprecation markers for example.
The link you added is about a simplified documentation syntax and is not related with Markdown. Still your question legitimate: you want a simplified documentation syntax that understands Markdown within documented elements. All right... I don't know any parser that does that then... I'll dig in the link you posted in your update ;o)
"while documenting code needs a syntax to relate documentation elements to ..." Absolutely, I included one idea about how to achieve that in my original question :-) XML is not required for that. Java has its own Javadoc syntax which gets along with much less "noise". Markdown would have been even greater.
6

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.

Improve this answer

2 Comments

ad 1, I am aware of this. However I found that at least as for the summary text, it is displayed just as nicely in IntelliSense if you omit the summary element. As for the rest, I would have hoped that there are (or would be to come) Visual Studio extensions that do support that type of documentation. ad 1b (documentation for others referencing the library): True. Yet another tool would be required that produces a proper XML file from the inline documentation. ad 2. _... which is a shame
Notwithstanding the desire to use markdown, Sandcastle Help File Builder is pretty great. Also, if my memory is correct, Scott Gu demoed a Visual Studio extension several years ago that took advantage of the WPF editor rendering to allow code comments to be automatically displayed as they would be when viewing in a doc viewer. I don't think this ever saw the light of day, but it would go along way towards addressing this question.
1

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

Improve this answer

Comments

0

You can use Vsxmd (https://www.nuget.org/packages/vsxmd). More details on how to use you can find on github page of the package (https://github.com/lijunle/Vsxmd)

Improve this answer

Comments

Start asking to get answers

Find the answer to your question by asking.

Ask question

Explore related questions

See similar questions with these tags.