Solución:
La forma predeterminada de documentar el código C # en Visual Studio es mediante comentarios de documentación XML. En mi opinión, esta es la mejor manera de utilizar el código C # porque el soporte para esto ya está integrado en Visual Studio (finalización automática de etiquetas de comentarios, advertencia sobre parámetros faltantes o mal escritos, …). Para documentar un método, simplemente escriba tres barras (///) delante del cuerpo del método, y Visual Studio insertará una plantilla de comentario vacía para que la llene, así:
/// <summary>
///
/// </summary>
/// <param name="bar"></param>
private void Foo(int bar)
{
// ...
}
Puede configurar Visual Studio para generar un archivo XML a partir de todos los comentarios, que luego se introduciría en un generador de documentación como Sandcastle. Si desea utilizar Doxygen, esto no es un problema, ya que admite el análisis de comentarios XML.
Para resumir: Recomendaría usar comentarios XML sobre comentarios especiales de Doxygen para código C #. De esta forma tienes todas las opciones. Puede generar documentación en el diseño estándar de Doxygen con el que su organización está familiarizada (porque Doxygen admite comentarios XML) y además tiene la opción de generar documentación en un formato conocido por los desarrolladores de .NET (con Sandcastle y Sandcastle Help FileBuilder).
Ah, y también prueba GhostDoc …
Hay varias opciones para la documentación:
-
La forma gratuita de Microsoft. Utilice los comentarios de la documentación de DocXml y luego Sandcastle o una herramienta similar para crear documentación al estilo MSDN. La ventaja de esto es que Visual Studio reconoce la documentación (colorea la sintaxis de los comentarios) y el sistema Intellisense la recoge instantáneamente (por lo que si pasa el puntero del mouse sobre un método al que está llamando, la información sobre herramientas mostrará el información de resumen y parámetros que ingresó en el comentario del documento)
-
El sistema Doxygen gratuito. Esto es más fácil de usar y más flexible, pero no es compatible con Visual Studio, por lo que pierde las ventajas de intellisense y coloración de sintaxis. En el lado positivo, Doxygen analiza el formato DocXml, por lo que puede obtener lo mejor de ambos mundos utilizando el formato DocXml con Doxygen para generar la ayuda externa.
-
Productos comerciales como DocumentX, que le permiten editar la documentación en una ventana WYSIWYG.
Recomendaría comenzar con los comentarios de DocXml y Doxygen para generar la ayuda externa, ya que esa es la forma más barata y fácil de comenzar, y conserva todas las mejores características de VIsual Studio (intellisense, etc.).
También te sugiero que mires mi complemento, Atomineer Pro Documentation, que hace que la generación y actualización de los comentarios en formato DocXml, Doxygen, Qt o JavaDoc sea mucho más rápida y sencilla dentro de VS, un complemento ideal para Doxygen y Sandcastle.
Doxygen puede consumir comentarios de documentos de C # (///) sin problemas. Documente su código como de costumbre y ejecute doxygen para escanearlos en archivos html, chm y pdf independientes. Este es, con mucho, el enfoque más versátil, simple y no invasivo.
Si bien doxygen no está integrado en Visual Studio, viene con un IDE simple y puede programarse trivialmente como una herramienta externa personalizada. Personalmente, he integrado doxygen en mis scripts de compilación y funciona a la perfección.
Finalmente, doxygen es multiplataforma (lo cual es una ventaja si alguna vez necesita realizar la migración a Mono) y es significativamente más rápido que SandCastle (tanto para configurar como para ejecutar).
Este es un ejemplo de salida de Doxygen para código C # en un proyecto ~ 1Mloc: https://web.archive.org/web/20160313075951/http://www.opentk.com/files/doc/annotated.html