Использование Markdown для документации по исходному коду

Я ищу альтернативу документации исходного кода на языке С#, в которой по самой природе 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 с другой формулировкой, тем самым улучшив шансы будущих посетителей найти их информацию.

Update:

Я предполагаю, что я, наконец, нашел другой вопрос, используя другую поисковую систему: Markdown для автоматического создания doc?. Кажется, что Doxygen поддерживает Markdown. Doxygen поддерживает С#. Но это, вероятно, далеко не так, как для требований, упомянутых @Sam Harwell.

Ответы

Ответ 1

Эта суть делает работу довольно хорошо: https://gist.github.com/formix/515d3d11ee7c1c252f92

Полученный документ выглядит так: https://github.com/formix/MegaCityOne/blob/master/MegaCityOne/doc/api.md

Ответ 2

Теоретически, ваш пример может быть использован для предоставления файлов документации для проектов С#. Однако я рекомендую вам избегать этого подхода по следующим причинам.

Visual Studio не сможет напрямую использовать комментарии. Они должны будут запускаться через процессор Markdown для создания файлов документации XML, предварительно отформатированных до работы. Это означает, что вы всегда сможете получить надлежащую документацию для проектов, на которые ссылаются, а не для текущего проекта. Кроме того, если вы не генерируете вывод XML, то вы не производите каких-либо результатов, которые другие разработчики могут использовать, когда они ссылаются на вашу библиотеку.
Как Roslyn, так и проект SHFB работают над улучшением поддержки документации XML для поддержки IntelliSense. В это время SHFB фокусируется на показе своих пользовательских тегов документации (например, <preliminary/> и <see langword="null"/>), а Roslyn фокусируется на поддержке IntelliSense для значения атрибута cref тегов see и seealso. Насколько мне известно, нет поддержки альтернативного метода документирования кода С#.

Ответ 3

Вы можете использовать Vsxmd (https://www.nuget.org/packages/vsxmd). Подробнее о том, как использовать, вы можете найти на странице пакета github (https://github.com/lijunle/Vsxmd)

Ответ 4

Docfx

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

DocFX является генератором документации API для .NET, который в настоящее время поддерживает С# и VB. Он генерирует справочную документацию API из комментариев с тройным слешем в вашем исходном коде. Он также позволяет использовать файлы Markdown для создания дополнительных тем, таких как учебные пособия и инструкции, а также для настройки сгенерированной справочной документации