Documentar con C# (Para Visual Studio 2008)

Bueno, una de las cosas que pocas veces realizamos es el crear documentación de las clases que hemos realizados, o bien, se crea dicha documentación, pero reinventando la rueda.
C# al igual que sus hermanos lenguajes .Net, tiene la opción de Generar documentación, a través de comentarios con 3 slash (///) dentro del código fuente. Dichos comentarios son almacenados en un archivo XML definido.
Para crear un comentario de documentación debes seguir el siguiente ejemplo.



Para generar la documentación, la sintaxis es la siguiente:

csc tuClase.cs /doc:tuDocumentacion.xml

Esto quiere decir que toma todos los comenta y los almacena en el archivo xml (en el caso del ejemplo seria "tuDocumentacion.xml".

Ahora bien, Si trabajamos con Visual Studio, le podemos decir que al generar o compilar, cree su archivo xml, esto se encuentra en Propiedades del proyecto (proyecto, no solución) -> Generar -> y luego hay que seleccionar la casilla que dice "Archivo de documentacion XML:" (nota: se debe chequear tanto para Debug, como para Release).



Existe un Add-On para Visual Studio 2003, 2005 y 2008 llamado GhostDoc. Dicho Add-On nos ayuda en crear los comentrarios, tan sólo posicionandonos sobre nuestra clase o método que queremos generar su documentación y presionando el botón derecho, le decimos "Document this".



Una vez creada nuestra documentación, debemos darle un formato (tipo msdn o chm(ayuda windows). Para aquello debes descargar SandCastle quién te genera documentación tipo msdn, ahora bien, si quieres generar los arhivos tipo ayuda al estilo windows, o sea los CHM, debe además descargar HTML Help Workshop.
El unico problema de SandCastle es que como no posee interfaz gráfica y el proceso es un tanto largo, la creación de la documentación se hace un tanto complicada...pero tranquilo, existe (n) una (varias) ide que abstraen la complejidad, una de ellas (y que he probado sin complicación) se llama SandCastleGUI.

Espero que sea de utilidad esta información y nos vemos pronto!!!!