.net - traduccion - Castillo de arena: ¿sigue siendo lo correcto? ¿O hay alternativas?
sandcastle juego (7)
Microsoft Sandcastle es definitivamente el camino correcto a seguir. La principal alternativa (que ofrece algo NDoc conjunto de características de Sandcastle) es NDoc , pero la última versión es mucho más antigua, ¡en enero de 2005!
Aunque todavía se encuentra técnicamente en la etapa de lanzamiento previo (tardía), de hecho es una herramienta bastante estable. La pequeña cantidad de errores se han corregido con parches, disponibles en CodePlex como parte del proyecto Sandcastle Styles . También hay una excelente interfaz gráfica de usuario, a saber, Sandcastle Help File Builder .
Sin embargo, no estoy seguro del futuro desarrollo de Sandcastle. Creo que es probable que Microsoft continúe trabajando / expandiéndose en algún momento, aunque no parece haber ninguna noticia de cuándo. Sin duda, es la única herramienta decente para crear la documentación adecuada para una biblioteca o aplicación .NET en este momento. Por supuesto, a menudo puede escapar utilizando más herramientas "ligeras" para proyectos pequeños / archivos de ayuda. Las principales alternativas que he notado son tanto comerciales como inferiores a Sandcastle.
Generar documentación a mano / usar automatización personalizada es probablemente factible en ciertos casos, pero solo para proyectos pequeños (que no es probable que se expandan).
Me pregunto: el último lanzamiento de Sandcastle es de mayo de 2008, y aún se encuentra en la lista de Pre-Release Software / CTP y aún no tiene licencia, ya que el EULA específicamente dice:
2.TERM. El término de este acuerdo es hasta el 1 de septiembre de 2007, o el lanzamiento comercial del software, lo que ocurra primero.
Como Sandcastle es bastante "pesado" de todos modos, me pregunto si todavía es lo correcto o si hay alternativas para crear la documentación XmlDoc. (Alternativas = algo que puedo ejecutar desde mi compilación para generar al menos HTML, preferiblemente PDF también).
Nadie mencionó Docu, un proyecto reciente iniciado por James Gregory, líder de desarrollo en FluentNHibernate.
Es una herramienta muy simple y fácil de usar que genera documentación html a la rdoc . Puede modificar plantillas fácilmente ya que Docu usa Spark como motor de visualización.
Aquí está la documentación de FluentNHibernate construida con Docu.
Para usar efectivamente Sandcastle, como Noldorin señaló anteriormente, también necesita usar Sandcastle Styles y Sandcastle Help File Builder (SHFB). Todos ellos tenían un nuevo lanzamiento a mediados de 2010, por lo que son definitivamente herramientas actuales.
Sin embargo, incluso con la GUI limpia y simple proporcionada por SHFB, hay una serie de cuestiones que puede necesitar o desear considerar para producir un conjunto de documentación profesional y ordenado. Mi artículo (" Taming Sandcastle: Guía para programadores de .NET para documentar su código ") que documenta mi experiencia con una variedad de posibles escollos, publicado en Simple-Talk.com en septiembre de 2010, puede ahorrarle tiempo, esfuerzo y agonía: -).
Otro recurso útil: en octubre de 2010, seguí el artículo con un gráfico de una página que resume el léxico de comentarios de la documentación XML para SHFB.
Que yo sepa, Sandcastle sigue siendo una opción válida. Lo he usado muchas veces en el pasado reciente y no tengo problemas. Puede consultar esta página en MSDN y desplazarse hacia abajo a la sección "Documentación" para conocer otras buenas opciones:
anyone-using-ndoc-or-a-similar-tool una lista corta de algunas herramientas de documentación en esta pregunta de SO: anyone-using-ndoc-or-a-similar-tool
Creo que SandCastle es la mejor herramienta de código abierto actualmente (para documentar proyectos .NET), pero existen varias herramientas comerciales que pueden proponer un mejor rendimiento y más funciones, por lo que si tiene un presupuesto para uno de ellos, vale la pena al menos evaluar qué valor podría aportarle.
DocProject pena echar un vistazo a DocProject . Se quita mucho el dolor de trabajar con el castillo de arena.