Using Markdown for source code documentation
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.
Answer
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