c# - fuente - generar documentacion visual studio 2017

Usando Markdown para la documentación del código fuente

Question

Estoy buscando una alternativa a la documentación de código fuente XML de C # que introdujo por la naturaleza misma de XML una gran cantidad de ruido que es pesado para la vista y más trabajo para escribir:

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

En su lugar, me gustaría usar Markdown para la documentación:

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

Podría apostar que encontré una pregunta y una respuesta para exactamente esto en Stackoverflow antes. Lamentablemente no logro encontrarlo más. Probé todas las variaciones de palabras clave de búsqueda que podía imaginar sin suerte. Así que espero que alguno de ustedes encuentre el duplicado. Al menos mi pregunta agregará algo de valor a SO al proporcionar un "proxy" a las preguntas y respuestas existentes con una redacción diferente, mejorando así las probabilidades de que los futuros visitantes encuentren su información.

Actualizar:

Supongo que finalmente encontré la otra pregunta usando un motor de búsqueda diferente: ¿ Markdown para la generación automática de documentos? . Parece que Doxygen soporta Markdown. Doxygen también es compatible con C #. Pero esto probablemente no sea de gran ayuda en cuanto a los requisitos que mencionó @Sam Harwell.

Answer 1

Esta idea hace el trabajo bastante bien: https://gist.github.com/formix/515d3d11ee7c1c252f92

El documento resultante se ve así: https://github.com/formix/MegaCityOne/blob/master/MegaCityOne/doc/api.md

Answer 2

Puede usar Vsxmd ( https://www.nuget.org/packages/vsxmd ). Puede encontrar más detalles sobre cómo usarlo en la página github del paquete ( https://github.com/lijunle/Vsxmd )

Answer 3

Teóricamente, su ejemplo podría usarse para proporcionar archivos de documentación adecuados para proyectos de C #. Sin embargo, le recomiendo que evite este enfoque por las siguientes razones.

1. Visual Studio no podrá consumir los comentarios directamente. Deberán ejecutarse a través de un procesador Markdown para producir archivos de documentación XML con el formato correcto antes de trabajar. Esto significa que solo podrá obtener la documentación adecuada para los proyectos de referencia y no para el proyecto actual . Además, si no está generando una salida XML, entonces no está produciendo ninguna salida que otros desarrolladores puedan usar cuando hacen referencia a su biblioteca.

2. Tanto Roslyn como el proyecto SHFB están trabajando para mejorar el soporte de IntelliSense para comentarios de documentación XML. En este momento, SHFB se enfoca en mostrar sus etiquetas de documentación personalizadas (por ejemplo, <preliminary/> y <see langword="null"/> ), y Roslyn se enfoca en el soporte de IntelliSense para el valor del atributo seealso etiquetas see y seealso . Que yo sepa, no hay ningún impulso para admitir un método alternativo de documentar el código C #.