Parte I. Crear documentación XML en Visual Basic .NET

En este minitutorial vamos a ver los principios básicos para documentar nuestro código fuente para que así Visual Studio nos muestre la información en IntelliSense.

Cuando estamos programando qué útil es IntelliSense explicándonos cómo funcionan las funciones, propiedades, etc., y sus correspondientes parámetros, pero, ¿cómo podemos hacerlo nosotros en nuestro código? Pues de una forma muy sencilla e intuitiva.

Ejemplo IntelliSense

Primero vamos a empezar creando una clase la cual vamos a documentar. Para ello, en primer lugar creamos un nuevo proyecto y a ese nuevo proyecto (en principio será únicamente un formulario) le vamos a añadir una clase a la que llamaremos ClaseMostrarFormulario. El funcionamiento de esta clase es trivial, simplemente está compuesta por una serie de propiedades y un método. Las propiedades son para dar tamaño, color, texto y el tiempo que va a mostrar el formulario y tiene un método que hará que se muestre el formulario. El código de la clase es el siguiente.

Public Class ClaseMostrarFormulario


    Private TextoCabece As String = "Prueba"
    Private ColorDia As Color = Color.White
    Private TamañoDia As Size = New Size(100, 100)
    Private frm As New Form
    Private SegundosAct As UInteger = 1
    Private WithEvents Temporizad As New Timer

    Public Property TextoCabecera As String
        Get
            Return TextoCabece
        End Get
        Set(value As String)
            TextoCabece = value
        End Set
    End Property

    Public Property ColorDialogo As Color
        Get
            Return ColorDia
        End Get
        Set(value As Color)
            ColorDia = value
        End Set
    End Property

    Public Property TamañoDialogo As Size
        Get
            Return TamañoDia
        End Get
        Set(value As Size)
            TamañoDia = value
        End Set
    End Property

    Public Property SegundosActivo As UInteger
        Get
            Return SegundosAct
        End Get
        Set(value As UInteger)
            SegundosAct = value
        End Set
    End Property


    Private Property Formulario As Form
        Get
            Return frm
        End Get
        Set(value As Form)
            frm = value
        End Set
    End Property


    Public Sub MostrarDialogo()
        Formulario.Size = TamañoDialogo
        Formulario.Text = TextoCabecera
        Formulario.BackColor = ColorDialogo
        Temporizad.Enabled = True
        Temporizad.Interval = SegundosActivo * 1000
        Temporizad.Start()
        frm.Show()
    End Sub



    Private Sub Temporizar_activo() Handles Temporizad.Tick
        frm.Hide()
        Temporizad.Stop()
    End Sub
End Class

Como se puede observar la clase es muy sencilla, pero para este ejemplo nos vendrá bien. Ahora en el formulario creamos un botón y asignaremos el siguiente código:

Private Sub Button1_Click(sender As Object, e As EventArgs) Handles Button1.Click
 'Instanciamos a la clase
 Dim Dialogo As New ClaseMostrarFormulario
 'Le damos color al formulario
 Dialogo.ColorDialogo = Color.Aquamarine
 'Le damos tamaño
 Dialogo.TamañoDialogo = New Size(500, 500)
 'Texto de cabecera
 Dialogo.TextoCabecera = "¡Mi texto de cabecera!"
 'Tiempo que estará abierto el formulario
 Dialogo.SegundosActivo = 3
 'Mostramos el cuadro de diálogo
 Dialogo.MostrarDialogo()
End Sub

Ejecutamos la aplicación y se mostrará el cuadro de diálogo que vemos en la imagen (durante 3 segundos).

Programa mostrando cuadro de diálogo

Hasta ahora no hemos aprendido nada nuevo, pero ahora vamos al lío. Como se observa, el nombre de las propiedades de la clase y el método son muy intuitivos, pero imagínese que la propiedad SegundosActivos se llamase TiempoActivo, ¿cómo sabríamos el tipo de unidad utilizada?, serían milisegundos, segundos... Pues para eso vamos a ver cómo documentar la clase de tal forma que el asistente de Visual Studio (IntelliSense) muestre una explicación de la propiedad, o un parámetro de una función, por ejemplo.

Volvemos a abrir el código fuente de la clase (ClaseMostrarFormulario), nos situamos encima de la propiedad TextoCabecera y pulsamos tres veces el carácter de comentario (''') y, voilà, ha aparecido una plantilla XML que podemos rellenar.

Y ya estamos listos para documentar esta propiedad. Como vemos, de forma automática ha generado un campo resumen (summary), valor (value), retorno (returns) y comentarios (remarks). En este caso, el campo returns y value vamos a eliminarlo porque no nos interesa demasiado en esta propiedad, y vamos a rellenar los campos con la siguiente información.

''' 

''' Esta propiedad determina el texto de la cabecera del cuadro de diálogo.
''' 
''' El valor predeterminado es "Prueba".
Public Property TextoCabecera As String
    Get
        Return TextoCabece
    End Get
    Set(value As String)
        TextoCabece = value
    End Set
End Property

Ahora volvemos a nuestro formulario principal y vamos a ver qué nos muestra IntelliSense.

Resumen en IntelliSense

Como vemos nos muestra la información que hemos incluido en los comentarios XML, pero realmente no vemos toda, si queremos ver toda basta con hacer clic (dentro de Visual Studio) en Ver/Examinador de objetos, localizamos nuestra clase y la propiedad TextoCabecera y vemos toda la información.

Examinador de objetos

A continuación deberíamos hacer lo mismo para todas las propiedades y el método y nuestra clase estaría documentada.

Ahora bien, vamos a incluir al método MostrarDialogo un parámetro denominado TipoDialogo que indicará el tipo de cuadro de diálogo (si tiene borde, posibilidad de maximizar, etc.), siendo esta variable de tipo System.Windows.Forms.FormBorderStyle. El método quedaría tal que así.

Public Sub MostrarDialogo(ByVal TipoDialogo As System.Windows.Forms.FormBorderStyle)
     Formulario.Size = TamañoDialogo
     Formulario.Text = TextoCabecera
     Formulario.BackColor = ColorDialogo
     Formulario.FormBorderStyle = TipoDialogo
     Temporizad.Enabled = True
     Temporizad.Interval = SegundosActivo * 1000
     Temporizad.Start()
     frm.Show()
End Sub

Y una vez realizados los cambios, vamos a volver a poner los tres símbolos de comentario (''') y nos aparecerá automáticamente un campo (param name="TipoDialogo") para poder especificar información sobre el parámetro.

''' 

''' Muestra el cuadro de diálogo con las propiedades asignadas.
''' 
''' Variable del tipo System.Windows.Forms.FormBorderStyle que indica el tipo de borde del formulario.
''' Los valores predeterminados para el cuadro de diálogo son: Color-> blanco, Tamaño-> (100,100), Texto-> "Prueba", Tiempo -> 1 segundo
Public Sub MostrarDialogo(ByVal TipoDialogo As System.Windows.Forms.FormBorderStyle)
   Formulario.Size = TamañoDialogo
   Formulario.Text = TextoCabecera
   Formulario.BackColor = ColorDialogo
   Formulario.FormBorderStyle = TipoDialogo
   Temporizad.Enabled = True
   Temporizad.Interval = SegundosActivo * 1000
   Temporizad.Start()
   frm.Show()
End Sub

Además de todo esto, dentro de cada campo hay más etiquetas que se puede incluir, para poner, por ejemplo, código fuente, estructurar por párrafos y más. Vamos a ver un último ejemplo, pero para tener más información sobre estos parámetros les recomiendo este enlace (http://msdn.microsoft.com/es-es/library/ms172653(v=vs.90).aspx).

''' 

''' Muestra el cuadro de diálogo con las propiedades asignadas.
''' A continuación se muestra un ejemplo para utilizar este método
'''  Dim Dialogo As New ClaseMostrarFormulario
''' Dialogo.ColorDialogo = Color.Aquamarine
''' Dialogo.TamañoDialogo = New Size(500, 500)
'''  Dialogo.MostrarDialogo(Windows.Forms.FormBorderStyle.None)
''' 
''' 
''' 
''' Variable del tipo System.Windows.Forms.FormBorderStyle que indica el tipo de borde del formulario.
''' Los valores predeterminados para el cuadro de diálogo son: Color-> blanco, Tamaño-> (100,100), Texto-> "Prueba", Tiempo -> 1 segundo

Después de todo lo visto ya tenéis los conceptos básicos para empezar a documentar vuestro código. En la próxima entrega veremos cómo crear una guía visual al estilo MSDN para crear un archivo de ayuda con la documentación utilizando el programa Sandcastle.

Descarga el código fuente aquí: