Generar archivos de documentación (.chm) para programas desarrollados en C# usando SandCastle

Generar archivos de documentación (.chm) para programas desarrollados en C# usando SandCastle

Una pequeña introducción

Los principios de la programación orientada a objetos nos dicen que debemos programar de tal manera que agrupemos métodos y atributos que puedan ser aplicados a un objeto y que dicho objeto pueda ser utilizado y reutilizado de forma eficiente, una de las formas más eficientes para la reutilización de código es la creación de librerías o paquetes, en el caso de C# se llaman librerías y tienen la extensión .dll, las cuales pueden ser utilizadas posteriormente en otra aplicación y por otra persona, pero ya sea que creémos o no una librería, habrá momentos en los que querramos volver a utilizar un segmento de código desarrollado anteriormente y para ello debemos tener en mente la forma en que este código trabaja, esto es una razón muy importante entre otras para documentar nuestro código. Personalmente no lo consideraba tan importante hasta que tuve la necesidad de reutilizar mi código y entonces tuve que volver a estudiarlo en parte para recordar cómo trabajaba, qué hacía cada método y qué representaba cada parámetro de entrada, pero bueno, de ahora en adelante documentaré bien mis programas y librerías para que esto no vuelva a pasar :).

Entremos en materia:

Dentro del entorno de programación IDE de C# como Visual Studio 2010, un comentario se escribe simplemente escribiendo en el renglón superior de la porción a documentar tres veces el símbolo slash (///), esto solicitará la descripción de los datos correspondientes, se puede documentar en general cualquier parte

del código que se requiera, pero la parte principal son los constructores, métodos y atributos. para mayor información de cómo documentar y las etiquetas permitidas referirse a la página web: http://msdn.microsoft.com/es-es/library/b2s063f7(v=vs.100).aspx

El motivo de esta entrada es compartir una aplicación que me pareció muy buena para generar los archivos de ayuda de forma similar a una API, esta aplicación se llama SandCastle, así que explicaré sus funciones básicas (que realmente fué las que utilicé) y la forma de trabajar con él:

Primero que todo la página oficial del proyecto es: http://shfb.codeplex.com/

Una vez se descargue su más reciente versión (Microsoft dejó de mantener este software desde el año 2010 , pero el proyecto ha sido acogido  por codePlex) simplemente abrimos el instalador y seguimos las sencillas instrucciones y tenemos SandCastle instalado!

El siguiente paso para documentar nuestro software es indicarle al IDE de programación  que queremos que se genere el archivo XML con la representación de los comentarios (los cuales han sido incluidos en el archivo editor de la clase, anteponiendo ). Vamos al menú proyecto-> propiedades->build y buscamos la opción "XML Documentation File", activamos el checkbox si es el caso e indicamos el path relativo donde queremos que el archivo .xml sea generado. (El path o ruta es relativo con respecto al directorio de ubicación del proyecto, a mí me parece mejor indicar el path donde se genera el archivo dll en el caso de una librería por facilidad de acceso)

Listo, ahora cada vez que compilemos el proyecto, este archivo xml se actualizará  y podemos usar SandCastle para generar el archivo de ayuda basándose en él. 

Abrimos SandCastle, creamos un proyecto (File-new project) y obtendremos la pantalla de bienvenida y presentación donde en la parte izquierda tenemos las propiedades del proyecto, (aquí hay mucho por explorar, desde colocar la referencia al copyright, notas aclaratorias y opciones de visualización) pero para generar un archivo básico inicialmente estos parámetros pueden ser ignorados, lo importante por ahora es indicarle a SandCastle en qué lugar se encuentran ubicados nuestros archivos fuente para la documentación, esto se hace dando click derecho al elemento "Documentation Sources" y posteriormente a "Add Documentation Source", vamos al lugar donde se generó el archivo dll y lo seleccionamos, el archivo .xml también debe ser agregado, es por esta razón que recomendé ubicar el archivo .xml en el mismo directorio donde se genera el archivo .dll, En este caso al hacer doble click sobre alguno de ellos el otro se agregará automáticamente, la pantalla en este punto del proceso debe ser similar a la siguiente:

Una vez tengamos esto simplemente damos click en el botón de compilar o construir y listo, el archivo tardará un poco en generarse dependiendo de nuestro computador y el tamaño del proyecto. El archivo de ayuda .chm quedará guardado en el path que le indicamos al proyecto en SandCastle dentro de una carpeta por defecto llamada "help".

Espero les haya sido útil. Gracias :)