Menu
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.
926
Many technical writers find lots of benefits in using Markdown for their documentation. Some of these benefits are: Markdown provides semantic meaning for content in a relatively simple way. You can write rich formatted content extremely quickly (compared to writing directly in HTML tags)
The basic Markdown syntax allows you to create code blocks by indenting lines by four spaces or one tab. If you find that inconvenient, try using fenced code blocks. Depending on your Markdown processor or editor, you'll use three backticks ( ``` ) or three tildes ( ~~~ ) on the lines before and after the code block.
Fortunately, Markdown has full HTML support, so you can code a table in HTML and go right back to Markdown in the same document. Plus, it's much easier to read raw Markdown than it is to read raw HTML.
Its goal is to allow people “to write using an easy-to-read, easy-to-write plain text format, and optionally convert it to structurally valid XHTML (or HTML).” Because Markdown text files are plain text, you can use almost any text editor to open them.
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
106
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.
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.
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.
42
If you love us? You can donate to us via Paypal or buy me a coffee so we can maintain and grow! Thank you!
Donate Us With
