Me gustaría poder generar una documentación técnica del código fuente de mi aplicación y que quede escrita de tal forma que parezca a la ayuda del msdn o la del TechNet. Esto es posible mediante el uso del SandCastle y una herramienta que provee una interfaz gráfica que lo hace utilizable me refiero al SHFB Sandcastla Help File Builder.
Sandcastle es una herramienta que Microsoft distribuye de manera gratuita y su utilización es fundamental para generar documentación conceptual y técnica de las librerías de nuestras soluciones escritas en .Net Framework; Para crear la documentación técnica, Sandcastle toma básicamente un archivo .dll y un archivo de comentarios .xml, se apoya en la reflection y genera un archivo con un formato similar a la documentación técnica del MSDN y TechNet. La utilización de Sandcastle es muy compleja porque carece de Interfaz Gráfica de Usuario por tal razón su utilización nos remite a la línea de comandos, dichos comandos son molestos de escribir y ejecutar; y aunque se pueden crear archivos .bat que automaticen la tarea vale la pena mencionar que la creación de éstos demanda mucho tiempo y en consecuencia dinero.
El SHFB genera la documentacion en formato CHM, un sitio web con un indice entre otros formatos, si hay varias dll se crea un nodo principal en el índice que referencia dicha dll
Cómo instalarlo?
- Descarga e instala el HtmlHelp:
[http://go.microsoft.com/fwlink/?linkid=14188] - Descarga e instala el Sandcastle de Microsoft: [http://www.microsoft.com/downloads/details.aspx?FamilyID=E82EA71D-DA89-42EE-A715-696E3A4873B2&displaylang=en],
- Descarga e instalael Sandcastle Help File Builder:
[http://www.codeplex.com/SHFB/Release/ProjectReleases.aspx?ReleaseId=8261]
Una prueba de funcionamiento
1) Asegurate de tener el archivo xml de comentarios
en la carpeta bin de tu proyecto, busca la dll que quieres documentar, el nombre de la dll debe existir tambien con la extension xml por ejemplo Negocios.dll debe tener el archivo de comentarios Negocios.xml, de no ser así se puede crear fácilmente desde visual studio de la siguiente manera,
1. Clic derecho sobre el proyecto/propiedades
2. En la pestaña generar bajo la region Resultado das clic sobre el la caja de verificación:
Archivo de documentación XML
3. Guardar cambios y luego clic derecho sobre el proyecto/volver a generar
Abre el SHFB
1. Clic en Proyecto/Nuevo proyecto
2. Clic en el botón Add, navega hasta las ubicacion de los dos archivos el .dll y el .xml
3. Clic en documentación/Build Project
Listo!