valid - ¿El mejor sistema de documentación para.NET?
sandcastle visual studio (8)
No he usado un sistema de documentación antes y generalmente escribo comentarios a mano.
Sin embargo, creo que sería bueno usar un sistema de documentos para un nuevo proyecto.
¿Qué recomiendas? He oído hablar de Sandcastle, pero no estoy seguro de si es lo mejor que hay.
(Esto es para un proyecto de código abierto, por lo que debe ser gratuito).
No es gratis, pero para el registro: vsdocman de http://www.helixoft.com
Ahora también hay Docu .
El proyecto original de NDoc (mencionado por otros) está muerto, pero hay un nuevo proyecto llamado NDoc3 .
NDoc3 es compatible con .NET 2.0 - 3.5. Actualmente está disponible como una versión beta y funcionó muy bien para mí. No estoy seguro si el proyecto aún está activo: la última versión beta se lanzó en abril de 2009.
Sandcastle creará documentación en formato HTML, HTML Help 1.x (.CHM) o formato de archivo HTML Help 2.x (.HxS) a partir de sus comentarios XML en su código al estilo de MSDN que se puede buscar con tabla de contenido. , etc.
En teoría, hay muy poco trabajo de trabajo adicional que necesitaría hacer para obtener una documentación completa. También se puede diseñar usando hojas de estilo para que luzcan completamente diferentes.
Hay una aplicación (gratuita) en CodePlex llamada Sandcastle Help File Builder (SHFB) que puede ayudarlo a construir / configurar la documentación usando Sandcastle.
Personalmente, he usado esto y, en mi opinión, fue fácil de configurar usando SHFB para configurarlo. También puede programarlo para volver a compilar como parte de un proceso de compilación automatizado si desea utilizar la línea de comandos.
Encontré que Starcastle es bastante difícil de configurar, indocumentado e incluso algo problemático. Además, no me apetecía que el estilo vs2005 genere una página separada para un tipo y sus miembros. Starcastle es muy bueno para documentación pública grande como MSDN, pero para la documentación interna simple, recomiendo mdoc del proyecto Mono.
Para generar documentación a partir de un archivo de comentario XML y un ensamblado .NET, ejecute:
mdoc update -i comments.xml assembly.dll -o mono-xml-files
mdoc export-html mdoc-xml-files -o mdoc-html-output
Lo anterior convierte los comentarios en el propio formato XML de mdoc y lo convierte de nuevo en HTML.
En primer lugar, no veo cómo podría haber algo desafortunado en trabajar en un proyecto de código abierto;) Pero un intento de responder a su pregunta sería doxygen .
He estado usando doxygen en un proyecto C # hace unos años y su funcionalidad y opciones de salida son simplemente inmejorables. Es bastante fácil de configurar y ha incorporado soporte para C #. Además del HTML habitual, doxygen puede producir LaTeX, RTF, PostScript, PDF hipervinculado, HTML comprimido y páginas man de Unix. Puede leer y producir listas de todos los sabores de TODO, / todo, TODO, FIXME, BROKEN o cualquier otra ''anotación'' que usted o los codificadores hayan realizado en el código. Puede alinear imágenes y vincular internamente en la base de código en espacios de nombres, paquetes o lo que sea que su idioma denomine módulos hoy en día.
Dimitri (el autor de doxygen) es muy receptivo y útil y la comunidad en torno a doxygen también es muy activa.
Para comenzar, simplemente abra un mensaje y escriba:
Doxygen -g
y listo: ¡usted mismo tiene un archivo de configuración completamente documentado!
También hay un breve tutorial para usuarios de Windows aquí .
Sandcastle es genial. Reemplaza NDoc muy bien y es bastante fácil de configurar.
He escrito una entrada anterior con algunos enlaces que pueden resultar beneficiosos para mirar: DocProject vs Sandcastle Help File Builder GUI