¿Sirve de algo esos comentarios que ponemos en el código o sirve para entretenernos con el Intellisense?
En ocasiones nos puede ser útil documentar nuestro código y distribuirlo al equipo para que todos sean conscientes de los elementos disponibles sin tener que abrir veinte proyectos.
Sandcastle nos permite crear una ayuda tipo msdn con los elementos definidos en nuestros componentes.
Para generalo nos proporcionan varias herramientas por línea de comandos, pero lo mejor es utilizar un ejemplo «SandcastleGui.exe», que nos automatiza la creación.
Seleccionamos nuestro assembly y el fichero de comentarios, el tipo de documentación y el formato.
Para generar el fichero de comentarios de nuestro componente, simplemente entramos en las propiedades del proyecto, en «Build», marcamos «Xml documentation file». Esto hará que visual studio genere un fichero xml con todos los comentarios que hayamos puesto.
Como resultado tendremos una documentación con el siguiente formato:
Si queremos crear la ayuda en ficheros tipo chm necesitaremos tener instalado “htmlhelp workshop”, que es el módulo de Microsoft para crear ficheros “chm”.
Buenas!
Una muy buena herramienta para usar junto con SandCastle es el «SandCastle Help File Builder» (http://www.codeplex.com/SHFB), que proporciona una GUI para generar muy fácilmente todo el archivo de ayuda. Y con «todo» me refiero no sólo a la documentación de la API a partir de los comentarios, si no también el AdditionalContent (contenido HTML e imágenes que deseamos distribuir en nuestra ayuda) o el ConceptualContent (contenido estático que deseamos distribuir, que creamos usando MAML, un lenguaje basado en XML y que SandCastle convierte en HTML usando el mismo look-and-feel que los ficheros de ayuda de API).
Además «SandCastle Help File Builder», ayuda a automatizar y configurar muchas de las tareas de SandCastle. Para mi es casi imprescindible!
Saludos!