Como documentar Librerias y/o Ensamblados .Net

Bueno este tema normalmente es algo que a los programadores no nos gusta mucho, mmmm… bueno a la mayoría que conozco no nos gusta …. pero es una buena práctica que emprendí hace ya varios años y que recomiendo a todos que realicen esta practica.

En este tema algunos se preguntarán y de que sirve que documente cada función o clase que desarrolle, si al final entendiendo el codigo se entiende el funcionamiento de determinada función, este pensamiento o comentario puede surgir si nunca has creado la documentación de todos los ensamblados de tus proyectos y no has visto esa documentación ya recopilada así como la ayuda en MSDN o en el mismo Visual Studio sobre las clases del .Net Framework.

Para realizar esta tarea es necesario realizar un par de pasos en .Net y para eso les comento que en la Versión 2003 de Visual Studio solamente en C# venía disponible la creación de comentarios para cada función y/o clase, aunque existe VBCommenter que adiciona la misma funcionalidad al IDE del Visual Studio, despues de instalado se pueden crear los comentarios desde VB.

Lo anterior solamente aplica para la Version 2003 de Visual Studio, ya que desde la versión 2005 en adelante ya vuiene incorporado en el IDE para ambos lenguajes, ustedes se preguntarán porque esto es así, y la respuesta es porque Microsoft subdivide el desarrollo por equipos de trabajo y para el caso separan el compilador de C# con el compilador de VB, los equipos para ASP .Net de Windows Forms, y así sucesivamente; esto les facilita el desarrollo pero aveces como es el caso que les comento a nosotros nos da los dolores de cabeza por el echo que para un lenguaje exista ciertos servicios pero para el otro no como es el caso de Refactoring, bueno eso sería en otro post que lo comentare.

Continuando con lo de los comentarios lo primero que hay que hacer es posicionarse una línea antes de la función que queremos agregar el comentario y escribir 3 apóstrofos(‘) para VB y 3 slashs(///) para C#, automáticamente se crea el encabezado para los comentarios. El ejemplo que mostraré es con la versión VStudio 2008.

Ejemplo: Al hacerlo sobre una función como la siguiente queda el comentario automático de la siguiente forma.

”’ <summary>
”’
”’ </summary>
”’ <param name=”primerParametro”></param>
”’ <returns></returns>
”’ <remarks></remarks>
Public Function FuncionAComentar(ByVal primerParametro As String) As Integer
Return 1
End Function

¿y para que sirve cada tag del comentario?

- En Summary colocar la intención de la función

- En remarks alguna observación sobre el comportamiento.

- En returns lo que devolverá la función, si es un Sub o devuelve void para C# no aparecerá ese tag para ingresar comentario.

- Si se nota también se incluye un tag por cada parámetro de la función y en ellos podemos poner que debe de enviarse de parámetro o que es lo que espera recibir la función en dicho parámetro.

Para el caso de las Clases también se le puede poner comentario y solamente pondrá el tag de Summary y el de remarks.

Para el ejemplo anterior la clase ya con comentarios quedaría de la siguiente forma:

”’ <summary>
”’ Este es un ejemplo de como documentar. Funcion que no hace nada.
”’ </summary>
”’ <param name=”primerParametro”>Este argumento es del tipo String</param>
”’ <returns>
”’  1 : Si todo es procesado correctamente
”’  0 : Si ´no se realiza el proceso
”’ -1 : Si hay un error en el procesamiento
”’ </returns>
”’ <remarks>El proceso de documentación no es tedioso hasta que ya es parte de nuestra cultura de desarrollo</remarks>
Public Function FuncionAComentar(ByVal primerParametro As String) As Integer
Return 1
End Function

Cuando tengamos documentada nuestras clases y/o funciones entonces debemos proceder a compilar nuestra aplicación y en la configuración del proyecto asegurarnos que esta marcada la opción para crear los archivos XML de configuración, que serán creados a partir de los comentarios que hemos colocado a nuestras clases y/o funciones.

En Visual Studio y con nuestra solución abierta ir a las propiedades de cada proyecto y configurar que se creen los archivos XML de documentación. Ver imagen para ver como se configura el proyecto en .Net para que cree los archivos XML de documentación.

Con los proyectos ya compilados es el momento de crear la documentación, para esto necesitamos una herramienta adicional, para el caso en Visual Studio 2003 era necesario tener nDoc el cual todavía esta disponible, para VStudio 2005 desarrollaron NDoc2005 que fue alguna opción en su momento, pero surgió Sandcastle el cual a mi juicio es el mas completo (par SandCastle es necesario bajarse ademas del Help File Builder unas librerias de Sandcastle aqui).

Después de instalar ambos instaladores vamos a proceder a correr la aplicación. Inicio\Todos los Programas\Sandcastle Help File Builder\Sandcastle Help File Builder GUI, y ahi nos abrirá la siguiente ventana:

Le damos en File\New Project , y nos aparecera la pantalla de administración y configuración de la construcción de la documentación. A un costado derecho tenemos los ensamblados, exes, proyectos y /o referencias y a la izquierda tenemos la configuración de datos como el Nombre del archivo, si lo vamos a hacer en formato del archivo de ayuda(HelpFileFormat) puede ser HTMLHelp1 (chm), MSHELP1 y MSHELP2 que son para instalar la ayuda en en IDE .Net y leerla desde el mismo y la ultima opción es como Website que lo deja como ASPX o como HTML, la diferencia de ASPX a HTML es que con ASPX tiene la capacidad de mostrar Indice y Busqueda, lo cual no lo hace con HMTL puro.

Nos pide el nombre del archivo de proyecto y la ubicación. Para el ejemplo se ha creado una carpeta llamada “micarpeta” en “Mis Documentos”, y le pondremos de nombre al proyecto “prueba”.

Posteriormente veremos la configuración, donde nos posicionaremos sobre la sección “Project Explorer” a un costado derecho y sobre “Documentation Sources” le damos clic derecho y seleccionamos la opción “Add Documentation Source”.

Después nos pide que busquemos el XML(*.xml), el archivo Solución(.sln), archivo de proyecto(*.*proj , aqui se incluyen proyectos de Vb o C#), archivo de ensamblado (*.dll) o archivo ejecutable (*.exe), los DLL o EXE deben de ser Assembly .Net. Para el ejemplo buscar el archivo de proyecto que queremos documentar, en las imagenes lo mostrare con un proyecto de ejemplo de un proyecto de consola con una sola clase con el método que anteriormente mostré.

Posteriormente dejaremos la configuración por default y le damos clic en “Build the help file” sobre la barra de herramientas como se muestra en la imagen.

Aparecerá la sección Build Output que nos irá mostrando como en forma de Log las tareas realizadas, al finalizar nos dará el mensaje “Build completed successfully”, lo cual nos indica que termino satisfactoriamente y podemos ir a la carpeta donde dejamos el proyecto (para el caso del ejemplo fue “Mis Documentos\micarpeta” y ahi encontraremos una carpeta llamada “Help” la cual contiene el archivo creado con nombre “Documentation.chm” que es el que queda por default(para cambiarlo es la opción HTMLHelpName en la sección Project Properties), además es un archivo CHM porque por default el formato del archivo generado es el de HTMLHelp1.

Al abrir el archivo encontraremos la documentación que tenemos en nuestro proyecto, para el caso encontraremos algunas inconsistencias por la documentación del NameSpace con un mensaje como “[Missing <summary> documentation for "N:appPruebaDocumentacion"]“,  eso es porque no hemos agregado documentación para el namespace, además de que si tenemos algún parámetro o función que no este documentado aparecerán mensajes similares, los cuales tambien se podrían obviar configurando en Project Properties para que no aparecieran esos mensajes.

Aquí detallo algunas características de configuración de la sección “Project Properties”

- Build\HelpFileFormat: Aqui se tienen las opciones HtmlHelp1, MSHelp2, MSHelpViewer, Website para la creación de la documentación en el formato que se requiera.

- Comments\NamespaceSummaries: En esta sección se pueden agregar los comentarios para cada Namespace del Ensamblado o Solucion .Net que utilizemos.

- Help File\HelpTitle: Nombre que le da al titulo de la ventana en el archivo CHM, al navegador para el HTML y ASPX, al igual que para la ayuda que se puede poner en .Net.

- Help File\HTMLHelpName: Nombre del archivo de documentación, ya sea CHM o de Ayuda .Net

- Paths : aqui hav varias caracteristicas para cambiar las ubicaciones donde se crearan los archivos.

- Show Missing Tags: Aqui hay características para obviar mensajes de Error de que falta documentación en Métodos, NameSpace, Parámetros de Función/Método, Clases, Observaciones. Con esto se puede configurar como lo creamos conveniente.

- Visibility\ApiFilter: Con esta característica podemos filtrar alguna clase(s) o namespace(s) o método(s) que no queremos que aparezca en la documentación creada

En fin son muchas utilidades y/o configuraciones que podemos hacer y los invito a conocer mas la herramienta para que de ahora en adelante documentemos de mejor forma nuestros proyectos. Por cierto les cuento que esta misma herramienta es la que Microsoft utiliza para documentar el Framework de .Net que nosotros utilizamos en la ayuda de .Net, es una herramienta bastante funcional y que ayudará a que nostros productos para informáticos sean mas profesionales. Ademas hay varios estilos adicionales que tambien se encuentran disponibles en la red. Como http://sandcastlestyles.codeplex.com/

En algún momento les comentaré de como hacer ayuda para software comercial así como la de Office.

“El fracaso tiene mil excusas, el éxito no requiere explicación”