Comentarios XML en Visual Studio

A propósito de querer que nuestro código sea más legible no sólo para nosotros sino también para el resto, hoy vamos a hablar de los comentarios XML en Visual Studio.

Para agregar un comentario a un método o propiedad tenemos 2 opciones:

• Menú contextual “Insertar comentario”
• Escribir 3 comillas simples ‘’’

En cualquier caso nos encontraremos con algo como esto:

    ''' <summary>

    '''

    ''' </summary>

    ''' <param name="parametro1"></param>

    ''' <remarks></remarks>

    Public Sub Metodo1(ByVal parametro1 As String)

 

    End Sub   

   

A partir de aquí lo interesante es ver que comentarios XML podemos agregar, qué significado tienen cada uno de ellos y donde aparecerán en el entorno de Visual Studio para que después sean de utilidad mientras programamos.

La lista de etiquetas permitidas se puede encontrar en http://msdn.microsoft.com/es-es/library/ms172653(v=VS.80).aspx

Aunque no parece importante, si se quiere incluir un corchete de apertura o cierre como literal en cualquier etiqueta, hay que escribir &lt; y &gt;

Algunas etiquetas se comprueban en tiempo de compilación y generan warnings en caso de no estar correctamente escritas. Por ejemplo, si especificamos un
<param name=”parametroNoExiste”> recibiremos un warning.

Las etiquetas que se validan durante la compilación son:

• <exception>
• <include>
• <param>
• <permission>
• <see>
• <seealso>
• <typeparam>

Otro punto a tener en cuenta es donde se aplica el comentario y como es visible al usuario. Podemos ver ciertos atributos mediante Intellisense (<summary> y <param>), otros en el explorador de objetos (<summary>, <remarks>, <returns>, <param> y <exceptions>) y todos los demás no se ven “aparentemente” (estaría encantado de corregir este entrada de mi blog con cualquier aclaración al respecto) desde el IDE. Ahora bien, se generan igualmente en el fichero de documentación XML y con herramientas como SandCastle http://sandcastle.codeplex.com/ aparecerán con su tratamiento oportuno.

La lista completa de atributo es:

• <c>
• Indica que el texto dentro de una descripción es código.
• <code>
• Indica que el texto consiste en varias líneas de código.
• <example>
• Especifica un ejemplo para el miembro. Generalmente dentro de esta etiqueta se utiliza también <code>.
• <exception>
• Especifica las excepciones que se pueden producir.
• Incluye un atributo cref que tiene que apuntar a una clase de excepción existente.
• <include>
• Hace referencia a otro archivo que describe los tipos y miembros de su código fuente.
• <list>
• Define una lista o una tabla.
• <para>
• Especifica que el contenido tiene el formato de un párrafo.
• <param>
• Información sobre un parámetro.
• Aparece con Intellisense.
• Aparece en el explorador de objetos como la sección “Parámetros”.
• <paramref>
• Da formato a una palabra como un parámetro.
• Tiene un atributo name = “nombreParametro”.
• <permission>
• Especifica un permiso necesario para el miembro.
• Incluye un atributo cref que tiene que apuntar a una clase de excepción existente.
• <remarks>
• Notas
• Aparece en el explorador de objetos como la sección “Comentarios”.
• <returns>
• Informa sobre el valor de retorno del método.
• Aparece en el explorador de objetos como la sección “Valores devueltos”.
• <see>
• Especifica un vínculo a otro miembro.
• Utiliza un atributo cref.
• <seealso>
• Especifica un vínculo que aparece en la sección “Vea también”.
• <summary>
• Resumen breve del método.
• Aparece con Intellisense.
• Aparece en el explorador de objetos como la sección “Resumen”.
• <typeparam>
• Define un nombre y descripción de parámetro de tipo.
• <value>
• Especifica la descripción de una propiedad.
• Se establece además de <summary>.

Un saludo!