Etiquetas para documentar código en C# .NET

Si estas empezando en el mundo de la programación utilizando C# .NET.. o quizás siendo ya un poco experimentado en este ambiente.. seguramente te estarás preguntando como rayos documentar el código, me imagino que en algun momento has utilizado algunas de las etiquetas para este fin, pero las utilizas todas y sabes que significa cada una de ellas ??

Este artículo es una reseña sobre las diferentes etiquetas que se utilizan sobre métodos y clases para generar documentación.. bien puede ser utilizando SandCastle o para documentar los objetos sobre el desarrollo cuando estos son invocados.

Por ejemplo, agregando “///” al inicio de una clase, el entorno de desarrollo de .NET automáticamente genera una secuencia especial de comentarios sobre el código y se ve de esta manera:

/// <summary>
/// Pretendo construir un reloj y esta es la descripcion de este objeto
/// </summary>
public Color reloj
{
    private int hora { get; set; }
}

Y como resultado, al implementar el objeto reloj .. Visual Studio me mostraría como documentación lo que escribí dentro de la etiqueta summary.

Creo que este tipo de etiquetas son llamadas “doc-comments tags” y forman parte del intellisense del editor de código de Visual Studio .. utilicé el ejemplo de “summary” porque virtualmente en cada miembro sea clase, método, propiedad, evento, etc.. se puede utilizar.. A continuación muestro una tabla con todas las etiquetas necesarias para documentar completamente un proyecto de software, veamos.

<summary>

Requerido
Se utiliza usualmente para describir un objeto. Es la primera línea de las etiquetas de la documentacion. También es utilizado para ayudar al Intellisense cuando se muestra un tooltip sobre un objeto.

<remarks>

Opcional
Se utiliza para escribir una descripción detallada de un objeto o método.

<example>

Opcional
Se utiliza para describir ejemplos sencillos de la implementación.

<seealso>

Opcional
Agrega enlaces asociados al método.

<param>

Requerido
Describe un parámetro en un método, también es mostrado en el intellisense.

<typeparam>

Requerido para cada parámetro de tipo genérico
Describe un parámetro o método de tipo genérico.

<returns>

Requerido en cada método que retorna un valor
Se utiliza para describir el valor a retornar por un método.

<exception>

Opcional
Describe una excepción que podría ser lanzada por un método.

<permission>

Opcional
Se utiliza para describir el nivel de acceso a un método

<include>

Opcional
Utilizado para incluir en la documentación un archivo o parte de otro en el código

<para>

Opcional
Utilizado para definir un bloque, solo se utiliza a nivel del elemento de documentación.

<list>

Opcional
Crea una lista con uno o diferentes formatos (bullet, number, table) .. se utiliza solamente a nivel del elemento de documentación.

<code>

Opcional
Se utiliza para especificar el formato que tendrá el código.

<c>

Opcional
Similar al anterior, la unica diferencia es que “code” permite escribir en multiples líneas.

<see>

Opcional
Se utiliza para definir un enlace a una página interna (cref) o externa (href).

<paramref>

Opcional
Hace referencia a un parámetro dentro de otra etiqueta

<typeparamref>

Opcional
Hace referencia a un tipo de parámetro genérico

La información completa incluyendo ejemplos y discusión sobre su uso la pueden encontrar en el sitio de ayuda de microsoft (MSDN): http://msdn.microsoft.com/en-us/library/5ast78ax.aspx

Jack Fiallos

Co-fundador de Qbit Mexhico, usuario de linux, Developer en tecnologías web.. Nicaragüense, centro en basketball, primer centro en rugby y pintor los fines de semana. Ortögrafo y ambientalista psicológico (de escritorio).. ese soy yo!

Si te ha servido compártelo y difunde nuestro blog..