Documentación XML en C#

Índice

0. Introducción
1. Documentación XML
2. Etiquetas Estándar
2.1 <summary>
2.2 <remarks>
2.3 <param>
2.4 <returns>
2.5 <exception>
2.6 <permission>
2.7 <example>
2.8 <c>
2.9 <code>
2.10 <see>
2.11 <seealso> 
2.12 <paramref>
2.13 <list>
2.14 <para>
2.15 <include>
3. Etiquetas Definidas por el Programador
4. Prefijos XML y Referencias Cruzadas
5. Conclusiones
6. Glosario
7. Literatura & Enlaces

0. Introducción

Escribir la documentación de nuestros programas debe ser tan común como escribir buen código. Veremos en este artículo cómo podemos documentar eficientemente el códido de los tipos y sus respectivos miembros usando el lenguaje de marcado extensible -XML- embebido en código C#. Describiremos las etiquetas estándar disponibles para agregar resúmenes, comentarios, parámetros, retornos, excepciones, entre otros, en el mismo código que escribamos para nuestras soluciones.

1. Documentación XML

En C# podemos documentar tipos y sus miembros a través de marcas que determinan una región de código. Esta documentación se ha describir antes de la declaración del tipo o miembro. e.g.:

/// <summary>

/// Crea la ventana principal de la aplicación.

/// </summary>

public Principal()

{

// Implementación...

}

Notemos que el inicio de un comentario empieza con tres caracteres de barra creciente o /. En el ejemplo previo, usamos la etiqueta </summary> para delimitar el resumen asociado al constructor Principal. Este resumen será el que se muestre en IntelliSense cuando referenciamos el miembro en el editor de código.

Figura 1. Cuadro de IntelliSense para mostrar la documentación de un miembro.

Una versión, sintácticamente, alternativa para el anterior código de documentación es:

/// <summary> Crea la ventana principal de la aplicación. </summary>

public Principal() { ... }

En lugar de utilizar el carácter de forward slash (/) podemos recurrir a la versión con asteriscos, así:

/**
  <summary>rea la ventana principal de la aplicación</summary>
*/

Notemos aquí que es mandatorio utilizar dos astericos (**) al empezar la región del comentario.

Ejemplo de uso:

Archivo C# Principal.cs [Enlace alternativo][Enlace alternativo]:

Compilemos esta clase usando la directiva /doc:

1. csc /target:exe /doc:Principal.xml Principal.cs

Luego tendremos el siguiente archivo XML:

Archivo XML Principal.xml [Enlace alternativo][Enlace alternativo]:

Este archivo XML puede ser usado para generar archivos CHM o HTML con herramientas tales como Sandcastle [3] o NDoc [2].

2. Etiquetas Estándar

A continuación las etiquetas estándar disponibles para documentar código C# [1]:

2.1 <summary>

<summary>...</summary>: muestra resumen de un tipo o de un miembro. Normalmente expresado en una frase simple.

2.2 <remarks>

<remarks>...</remarks>: texto descriptivo adicional para un tipo o un miembro.

2.3 <param>

<param name="nombre_parametro" />...<param>: Explicación de un parámetro de un método.

2.4 <returns><

<returns>...</returns>: Describe el valor de retorno de un método.

2.5 <exception>

<exception cref="tipo_excepcion">...</exception>: Describe la excepción que un método podría lanzar. Opcionalmente podemos especificar el tipo de la excepción en cref.

2.6 <permission>

<permission cref="tipo">...</permission>: Especifica un tipo IPermission [4] requerido por el tipo o miembro.

2.7 <example>

<example>...</example>: Indica un ejemplo de código fuente. Esta etiqueta es usada por generadores de documentación (e.g., Sandcastle, NDoc).

2.8 <c>

<c>...</c>: Fragmento de código de una sóla línea. Por lo general, esta etiqueta es parte de <example>.

2.9 <code>

<code>...</code>: Indica un fragmento de código de múltiples líneas. Por lo general, esta etiqueta es parte de <example>.

2.10 <see>

<see cref="miembro">...</see>: Referencia a otro tipo o miembro.

2.11 <seealso>

<seealso cref="tipo_o_miembro">...</seealso>: Referencia hacia otro tipo o miembro. Al usarse con un generador de documentación, la referencia es colocada en una sección llamada "See Also".

2.12 <paramref>

Con <paramref name="nombre"/<: Referencia un parámetro desde una etiqueta <summary> o <remarks>.

2.13 <list>

Indica a los generadores de documentación crear una lista numerada, no-ordenada (unordered), o lista al estilo tabla.

2.14 <para>

<para>...</para>: Generación de un nuevo párrafo.

2.15 <include>

<include file="nombre_archivo" path="tagpath[@name="id"]">...</include>

: une un archivo XML externo que contenga documentación.

3. Etiquetas Definidas por el Programador

El programador también puede definir sus propias etiquetas personalizadas. Tanto Sandcastle como NDoc soportan la especificación de etiquetas personalizadas en la documentación XML. Por ejemplo podríamos crear etiquetas como:

• <overloads>
• <threadsafety>
• <note>

En código C# las especificamos como cualquiera de las etiquetas estándar:

/// <overloads>

/// Sobrecarga el método Sumar.
/// </overloads>
public decimal Sumar() {...}

4. Prefijos XML y Referencias Cruzadas

Tanto los nombres de tipos y miembros son traducidos a identificadores (IDs) [1]. Para formar los identificadores se especifica un prefijo (Tabla 1) y la firma del tipo (identificador).

Figura 2. Prefijos de tipos en XML [1].

Veamos un ejemplo de cómo los IDs para los tipos y miembros son generados [1]:

Archivo C# PrefijosXml.cs [Enlace alternativo][Enlace alternativo]:

5. Conclusiones

Aunque para muchos pueda resultar una tarea tediosa documentar el código, es importante recordar que el código de alta calidad además de seguir patrones de eficiencia en la implementación de los algoritmos, debe estar documentado y clara y correctamente. Hemos aprendido los fundamentos de documentación en C# a través del uso de XML; el cual, como vimos, permite una estructuración clara y precisa de explicaciones, comentarios, referencias, etc.

Con el próximo artículo empezamos una nueva serie: Generalidades del Framework .NET.

6. Glosario

• Código
• Comentarios
• Documentación
• Identificador
• IntelliSense
• XML

7. Literatura & Enlaces

[1]: C# 5.0 in a Nutshell by Joseph Albahari and Ben Albahari. Copyright 2012 Joseph Albahari and Ben Albahari, 978-1-449-32010-2.
[2]: NDoc - Wikipedia, the free encyclopedia - https://en.wikipedia.org/wiki/NDoc
[3]: Sandcastle (software) - Wikipedia, the free encyclopedia - https://en.wikipedia.org/wiki/Sandcastle_(software)
[4]: IPermission Interface (System.Security) - https://msdn.microsoft.com/en-us/library/System.Security.IPermission.aspx

J