<Extraído originalmente de MSDN>
Introducción
La documentación del código suele ser el último paso que se realiza en el ciclo habitual de un proyecto. Mientras que la importancia de escribir documentación se ha señalado miles de veces, los desarrolladores suelen dedicar la mejor parte del ciclo de proyecto a la creación de nuevas características y, al final, realizan un trabajo mediocre a la hora de escribir la temida documentación. Siguiendo la popular frase limpia mientras cocinas que podemos ver en muchas cocinas, la mejor manera de producir una documentación de alta calidad para el proyecto sería crea la documentación mientras programas.
Documentación en línea mediante VBCommenter
Para ver cómo funciona VBCommenter, crearemos un nuevo proyecto de biblioteca de clases en Visual Studio .NET 2003, como se muestra en la figura 1. Tras crear una definición de clase, le agregaremos documentación XML.
Figura 1. Creación de un nuevo proyecto de biblioteca de clases
Para este ejemplo, he definido un sencillo Point. Una vez que se ha instalado VBCommenter, puede insertar un comentario XML. Para ello, escriba tres apóstrofos (') antes de una definición, propiedad, variables miembro o método de una clase (consulte la figura 2).
Figura 2. Adición de comentarios XML al código
Al presionar Entrar, se generará automáticamente la plantilla de documento XML que se muestra en la figura 3.
Figura 3. Plantilla de comentarios XML generada
Para configurar las opciones de VBCommenter, seleccione Tools -> VBCommenter Options (consulte la figura 4).
Figura 4. Configuración de VBCommenter
La lista 1 que aparece al final de este artículo muestra la documentación XML completa de la clase Point. A continuación, veremos algunas de las características más importantes.
< c >
< para >
< see >
< code >
< param >
< seealso >
< example >
< paramref >
< summary >
< exception >
< permission >
< value >
< include >
< remarks >
< list >
< returns >
Como ejemplo, veamos la documentación que he creado para uno de los métodos sobrecargados:
''' <overloads>
''' Calculates the distance between two points
''' </overloads>
'''
''' <summary>
''' Calculates the distance of a point from the origin
''' </summary>
'''
''' <returns>The distance between the current point and the origin
''' </returns>
''' <example> This sample shows how to call the <c>length()</c>
''' method
''' <code>
''' Dim ptA As New Point(3, 4)
''' Dim distance As Single = ptA.length()
''' </code>
''' </example>
'''
''' <remarks>
''' </remarks>
''' <history>
''' [Wei-Meng Lee] 9/27/2004 Created
''' </history>
Observará que hay un nuevo elemento, <overloads>, que no aparece en la lista especificada en la documentación de MSDN. El elemento <overloads> se utiliza para ofrecer una descripción general de los métodos que están sobrecargados. Veremos más adelante el efecto de este elemento cuando generemos la documentación mediante la herramienta NDOC. Observe que sólo es necesario especificar el elemento <overloads> en cualquiera de los métodos sobrecargados.
También se puede incluir ejemplos de código en la documentación mediante la etiqueta <example>. Para indicar que una palabra (o frase) es código, utilice la etiqueta <c>. Para varias líneas de código, utilice la etiqueta <code>.
Como los comentarios XML agregados al código dificultan su lectura, es posible ocultarlos si se hace clic en el signo menos "-" que aparece a la izquierda de la ventana de código. Para mostrar la documentación, haga clic en el signo más "+" como se muestra en la figura 5.
Figura 5. Cómo ocultar los comentarios
Una vez que ha comentado el código, al volver a generar las clases podrá encontrar un documento XML con el mismo nombre que el proyecto en la carpeta bin del proyecto. La figura 6 muestra la estructura del documento XML.
Figura 6. Documento XML generado por VBCommenter
Generación de la documentación
Con la documentación XML generada por VBCommenter, dispone de dos opciones relativas a la documentación:
Escribir las hojas de estilo de transformación XSLT que transformen el documento XML en un formato legible como HTML, PDF, etc.
Utilizar una herramienta de terceros para analizar automáticamente la documentación XML en los diferentes formatos de documentación que admite
En mi caso, he optado por la segunda opción y he utilizado NDoc (
http://ndoc.sourceforge.net/), un generador de documentación de código para .NET. NDoc es una herramienta gratuita de código abierto que genera documentación con varios formatos diferentes, incluido el formato de ayuda HTML tipo MSDN (.chm), el formato de ayuda de Visual Studio .NET (HTML Help 2) y las páginas Web tipo MSDN en línea.
La versión actual de NDoc es la 1.3 (en beta). Puede instalar NDoc para varias versiones de .NET: Mono, .NET 1.0 o .NET 1.1. Elegí .NET 1.1 como destino, puesto que utilizo Microsoft Visual Studio .NET 2003.
Tras instalar NDoc, deberá ver la ventana que aparece en la figura 7 al iniciar la aplicación. Puede elegir el tipo de documentación que desea generar mediante la selección del tipo de documentación en el cuadro de lista desplegable.
Figura 7. Inicio de NDoc
Haga clic en Add para agregar el nombre de archivo del ensamblado (consulte la figura 8). Una vez seleccionado el ensamblado (MyPoint.dll en la carpeta bin, en mi caso), aparecerá automáticamente el nombre de archivo del documento XML (el mismo nombre que el ensamblado, pero con la extensión .XML).
Figura 8. Adición de un ensamblado a NDoc
Puede agregar varios proyectos a la misma documentación si agrega cada ensamblado al proyecto NDoc.
Cuando esté preparado para generar la documentación, haga clic en el botón Build Documentation de la barra de herramientas como se muestra en la figura 9.
Figura 9. Generación de la documentación
Para ver la documentación, haga clic en el botón View Documentation de la barra de herramientas (figura 10).
Figura 10. Visualización de la documentación
Deberá ver la documentación generada como se muestra en la figura 11 (he expandido el árbol en el panel izquierdo para que muestre toda la documentación).
Figura 11. Documentación generada tipo MSDN
Centrémonos ahora en la documentación generada por las etiquetas de documentación que hemos comentado antes. Concretamente, veamos la documentación creada para el método sobrecargado length() como se muestra en la figura 12.
Figura 12. Comparación de las etiquetas XML y la documentación real generada
Como puede ver, el texto del elemento <overloads> se utiliza para proporcionar una descripción general del método sobrecargado, mientras que el elemento <summary> contiene la descripción real de cada método sobrecargado. Si no utiliza la etiqueta<overloads> para ninguno de los métodos sobrecargados, NDoc utilizará el texto que encuentre en el primer elemento <summary> como descripción general de los métodos sobrecargados.>
Haga clic en el primer método sobrecargado del método length() y vea la relación entre la etiqueta de documentación y la documentación real como se muestra en la figura 13.
Figura 13. Comparación de las etiquetas XML y la documentación real generada
Observe que el elemento <remarks> está vacío y, por tanto, la sección Remarks de la documentación también estará vacía. Si no incluye el elemento <remarks>, no se generará la sección Remarks.
Distribución de la documentación
Si observa la sección de propiedades de NDoc, la ubicación de la documentación generada se especifica si cambia el atributo OutputDirectory. En la figura 14, la documentación se guardaría en la carpeta c:\documentation.
Figura 14. Configuración del directorio de resultados de la documentación
Una vez generada la documentación, puede ver la lista de archivos generados en la figura 15.
Figura 15. Visualización de la documentación generada
Si desea distribuir la documentación de la clase, sólo tiene que distribuir el archivo que tiene la extensión .chm. Al ser una ayuda HTML compilada, no es necesario que los otros archivos HTML generados estén en la misma carpeta.
Conclusión
En este artículo, hemos visto cómo es posible agregar comentarios XML a las aplicaciones de Visual Basic .NET y utilizar una herramienta de terceros para generar la documentación de una aplicación. Todas las herramientas tratadas en este artículo son gratuitas, por lo que constituyen excelentes puntos de partida para empezar a documentar sus aplicaciones. Si conoce otras herramientas favoritas para generar documentación sobre el código, no olvide compartirlas conmigo en
wei_meng_lee@hotmail.com
Wei-Meng Lee (Microsoft .NET MVP, Singapore) es especialista en tecnología y fundador de Developer Learning Solutions, una compañía de tecnología especializada en la educación práctica sobre las últimas tecnologías de Microsoft. Wei-Meng participa con frecuencia como orador en conferencias internacionales y ha escrito y colaborado en la redacción de numerosos libros sobre .NET, XML y las tecnologías inalámbricas, entre los que se incluyen
Windows XP Unwired y
.NET Compact Framework Pocket Guide (ambos de O'Reilly Media, Inc.). También escribe con frecuencia para O'Reilly Network sobre temas que oscilan de .NET a Mac OS X.
Lista 1
''' -----------------------------------------------------------------------------
''' Project : MyPoint
''' Class : Point
'''
''' -----------------------------------------------------------------------------
''' <summary>
''' The Point class contains 2 properties, 1 overloaded constructor, and
''' 1 overloaded method
''' </summary>
''' <remarks>
''' If you need to use the Point class in the System.Drawing namespace, be
''' sure to reference it using the fullname, i.e. System.Drawing.Point
''' </remarks>
''' <history>
''' [Wei-Meng Lee] 9/26/2004 Created
''' </history>
'''
''' -----------------------------------------------------------------------------
Public Class Point
Private ptX, ptY As Integer
Private Shared count As Integer
''' -----------------------------------------------------------------------------
''' <summary>
''' Empty constructor
''' </summary>
''' <remarks>
''' Creates a new instance of the Point class
''' </remarks>
''' <history>
''' [Wei-Meng Lee] 9/26/2004 Created
''' </history>
''' -----------------------------------------------------------------------------
Public Sub New()
count += 1
End Sub
''' -----------------------------------------------------------------------------
''' <overloads>
''' Constructor
''' </overloads>
''' <summary>
''' Constructor with two parameters
''' </summary>
''' <param name="x"></param>
''' <param name="y"></param>
''' <remarks>
''' Creates a new instance of the Point class
''' <para>
''' Parameter x is assigned to the x-coordinate and
''' Parameter y is assigned to the y-coordinate
''' </para>
''' </remarks>
''' <history>
''' [Wei-Meng Lee] 9/26/2004 Created
''' </history>
''' -----------------------------------------------------------------------------
Public Sub New(ByVal x As Integer, ByVal y As Integer)
ptX = x
ptY = y
count += 1
End Sub
''' -----------------------------------------------------------------------------
''' <summary>
''' Property for x-coordinate
''' </summary>
''' <returns>The x-coordinate</returns>
''' <history>
''' [Wei-Meng Lee] 9/26/2004 Created
''' </history>
''' -----------------------------------------------------------------------------
Property x() As Integer ' sets the X coordinate
Get
Return ptX
End Get
Set(ByVal Value As Integer)
If Value < 500 And Value > -500 Then
ptX = Value
End If
End Set
End Property
''' -----------------------------------------------------------------------------
''' <summary>
''' Property for y-coordinate
''' </summary>
''' <returns>The y-coordinate</returns>
''' <history>
''' [Wei-Meng Lee] 9/26/2004 Created
''' </history>
''' -----------------------------------------------------------------------------
Property y() As Integer ' sets the Y coordinate
Get
Return ptY
End Get
Set(ByVal Value As Integer)
ptY = Value
End Set
End Property
''' -----------------------------------------------------------------------------
''' <overloads>
''' Calculates the distance between two points
''' </overloads>
'''
''' <summary>
''' Calculates the distance of a point from the origin
''' </summary>
'''
''' <returns>The distance between the current point and the origin
''' </returns>
''' <example> This sample shows how to call the <c>length()</c>
''' method
''' <code>
''' Dim ptA As New Point(3, 4)
''' Dim distance As Single = ptA.length()
''' </code>
''' </example>
'''
''' <remarks>
''' </remarks>
''' <history>
''' [Wei-Meng Lee] 9/27/2004 Created
''' </history>
''' -----------------------------------------------------------------------------
Public Function length() As Single
Return Math.Sqrt(Math.Pow(ptX, 2) + _
Math.Pow(ptY, 2))
End Function
''' -----------------------------------------------------------------------------
''' <summary>
''' Calculates the distance of a point from another point
''' </summary>
'''
''' <param name="pointOne">A Point object</param>
''' <returns>The distance between the current point and the
''' specified point
''' </returns>
'''
''' <example> This sample shows how to call the <c>length()</c> method
''' with a point specified
''' <code>
''' Dim ptA As New Point(3, 4)
''' Dim ptB As New Point(7, 8)
''' Dim distance As Single = ptA.length(ptB)
''' </code>
''' </example>
''' <remarks>
'''
''' </remarks>
'''
''' <history>
''' [Wei-Meng Lee] 9/27/2004 Created
''' </history>
''' -----------------------------------------------------------------------------
Public Function length(ByVal pointOne As Point) As Single
Return Math.Sqrt(Math.Pow(ptX - pointOne.x, 2) + _
Math.Pow(ptY - pointOne.y, 2))
End Function
End Class
, "Ejecutar como" - "Java Bean":
