Introducción

Con la constante reutilización de objetos ha sido necesario buscar la mejor manera de documentar las propiedades, métodos, clases etc. de los componentes que estamos realizando, la manera más común de documentación ha sido el crear elementos propios a manera de comentarios.

 

public XmlDocument ObtieneXML(string NombreArchivo) {           //Autor:    Misael Monterroca //Fecha:    Algún día de Julio                  //Propósito Crear un documento XML a partir de una secuencia de SQL //Regresa   XmlDocument //Parámetros NombreArchivo: String que contiene el nombre del archivo a utilizar

El problema de este tipo de documentación es que toda  queda embebida dentro del mismo componente, con lo cual, obliga a abrir nuestro código para poder tener una referencia de la documentación que contiene.

Otra práctica común es utilizar software específico para realizar la documentación, pero esta tarea resulta  tediosa ya que obliga a tener que trabajar en dos medios diferentes de una manera no sincronizada, con lo cual el margen de error aumenta al transcribir la documentación hacia este software..

Documentando con .Net

.Net Framework introdujo de manera nativa únicamente al compilador de C# la opción de generar un documento XML a partir  de etiquetas especificas escritas en formato XML

C#

///<summary>       /// Esta clase es de muestra para la documentación       ///</summary>       public class documentacion       {             public documentacion()             {                   //                   // TODO: Add constructor logic here                   //             }       }

El que únicamente este incluido de manera nativa en C#  no excluye a Vb.Net o algún otro lenguaje, ya que existen varios complementos   como VbCommenter que permiten tener una funcionalidad similar a la que ofrece el compilador de C#, el de generar un archivo XML a partir las etiquetas escritas.

VB

''' <summary> ''' Esta clase es de muestra para la documentación ''' </summary> Public Class documentacion     Public Sub New()     End Sub End Class

Etiquetas Recomendadas

Se puede incluir cualquier elemento del tipo XML, la única restricción es que los comentarios tienen que estar correctamente estructurados basándose en  los estándares del W3 referentes a la estructuración de un archivo XML http://www.w3.org/TR/REC-xml

Aún cuando puedes incluir cualquier etiqueta que consideres pertinente, es recomendable utilizar las recomendadas por Microsoft, ésto es para lograr una mayor adaptación y fácil entendimiento entre los diferentes desarrolladores, ya que al final de cuentas representan un estándar de documentación.

Aquí se presenta una tabla con las etiquetas recomendadas  que la mayoría de los generadores de documentación como NDoc  reconoce como validas, de igual manera se indica en donde pueden ser utilizadas.

Etiqueta	Clase	Estructura	Interfase	Enumeracion	Delegado	Constante	Propiedad	Método
<summary>	X	X	X	X	X	X	X	X
<remarks>	X	X	X	X	X	X	X	X
<para>	X	X	X	X	X	X	X	X
<list>	X	X	X	X	X	X	X	X
<example>	X	X	X	X	X	X	X	X
<code>	X	X	X	X	X	X	X	X
<param>							X	X
<paramref>							X	X
<returns>								X
<see>	X	X	X	X	X	X	X	X
<seealso>	X	X	X	X	X	X	X	X
<exception>							X	X
<permission>						X	X	X
<value>							X

<Summary>

Proporciona una descripción del tipo del miembro que estamos documentando, procure ser lo más especifico posible para que se entienda de manera sencilla el propósito que se logra obtener.

C#

///<summary> /// Proporciona las propiedades y métodos necesarios  Agregar, Actualizar y Eliminar un cliente. ///</summary>    public class Cliente

Resultado

<Remarks>

Normalmente es utilizado en conjunto con la etiqueta  <Summary>, y  su objetivo es proporcionar documentación a manera de  información complementaria con lo cual ayuda a ser un poco más especifico en cuanto a consideraciónes que deben de tomarse en cuenta.

///<summary> /// Proporciona las propiedades y métodos necesarios  Agregar, Actualizar y Eliminar un cliente. ///</summary>    ///<remarks>Recuerde utilizar esta clase solo cuando necesite modificar toda la información referente al cliente</remarks>      public class Cliente

Resultado

 

<Para>

Ayuda a separar la sección que se esté escribiendo en párrafos, con lo cual se logra mayor claridad en nuestra redacción.

///<summary>       ///<para>Proporciona las propiedades y métodos necesarios  Agregar, Actualizar y Eliminar un cliente.</para>       ///<para>Cuando utilice esta clase asegúrese de que utilizara todas las propiedades expuestas por la misma</para>       ///</summary>

Resultado

<List>

Permite crear listas numeradas en viñetas o tablas

<List type=”bullet”>           Lista en viñetas

<List type=”numeric”>      Lista numérica

<List type=”table”>            Crea una tabla

Para especificar los elementos que contendrá la lista o la tabla se especifica la etiqueta <item></item> especificando el contenido del elemento en la etiqueta <description></description>

///<para> Tipos de Cliente       ///         <list type="bullet">          ///               <item>                  ///                     <description>Vip</description>       ///               </item>       ///               <item>            ///                     <description>Cancelados</description>       ///               </item>       ///               <item>            ///                     <description>Inactivos</description>       ///               </item>       ///         </list>       ///   </para>

Resultado

Cuando se desee crear una tabla se puede especificar el encabezado  utilizando la etiqueta <listheader> que al igual que <item> utiliza la etiqueta <description> para especificar el contenido.

///<para>       ///         <list type="table">           ///               <listheader>       ///                     <description>Tipos de Cliente</description>       ///               </listheader>       ///               <item>                  ///                     <description>Vip</description>       ///               </item>       ///               <item>            ///                     <description>Cancelados</description>       ///               </item>       ///               <item>            ///                     <description>Inactivos</description>       ///               </item>       ///         </list>       ///   </para>

Resultado

Las etiquetas <item> y <listheader> cuentan con la etiqueta <term> la cual sirve para poder crear una tabla o lista a manera de poder especificar una columna que contenga la especificación de la información descrita.

///         <list type="table">           ///               <listheader>       ///                     <term>Tipo</term>       ///                     <description>Descripción</description>       ///               </listheader>       ///               <item>                  ///                     <term>A</term>       ///                     <description>Vip</description>       ///               </item>       ///               <item>            ///                     <term>B</term>       ///                     <description>Cancelados</description>       ///               </item>       ///               <item>       ///                     <term>C</term>          ///                     <description>Inactivos</description>       ///               </item>       ///         </list>

Resultado

<Example>

Especifica que la región pertenece a un ejemplo de utilización de codigo., ésta es utilizada normalmente en conjunto con la etiqueta <code>

///</summary>                                                                         ///<example> Este ejemplo demuestra como realizar la instancía del objeto                      ///</example>

Resultado

<Code>

Todo lo que esta contenido dentro de la etiqueta <code></code> es considerado como texto en forma de  código y  normalmente es utilizado dentro de una etiqueta <example>

///<summary>             /// Crea una nueva instancia de la clase Cliente             ///</summary>                                                                         ///<example> Este ejemplo demuestra como realizar la instancía del objeto             ///         <code>             ///               Cliente objCliente = new Cliente();             ///         </code>             ///</example>

Resultado

<Param> *

Esta etiqueta describe los parámetros que requiere una determinada función, Para utilizar esta etiqueta es necesario especificar sus atributos name el cual especifica el nombre del parámetro y description mediante el cual proporcionamos la descripción del parámetro, el texto escrito en el atributo description es mostrado desde el IntelliSense y en el Visor de Objetos

///<summary>             /// Crea una nueva instancia de la clase Cliente             ///</summary>             ///<param name="SoloActivos">Valor de tipo bolean el cual específica si únicamente debe mostrar clientes activos.</param>

Resultado

<paramref>

Cuando necesitemos hacer referencia a los parámetros que recibe alguna función podemos utilizar la etiqueta <paramref>, en su propiedad name es necesario especificar el nombre del parámetro al cual estamos haciendo referencia.

///<remarks>El valor predeterminado para el parámetro <paramref name="NumMaxReg"></paramref> es de  registros</remarks>

Resultado

<Returns>

Especifica el valor de retorno de una función

///<returns>Un datatable que contiene toda la información de la consulta</returns>

Resultado

<See> *

Esta etiqueta nos permite poner la referencia hacía un elemento de programación en nuestro código (namespace, clase), de manera que cuando el usuario de un clic en el elemento resaltado se podrá obtener más información del miembro solicitado. Comunmente puede ser utilizado para obtener más información del tipo al cual estamos haciendo referencia.

 

En el ejemplo hacemos referencia a System.Data.DataTable, ya que el tipo devuelto pertenece a dicho NameSpace.

///<returns>Un <see cref="System.Data.DataTable"/> que contiene toda la información de la consulta</returns>

Resultado

<SeeAlso> *

Es común, por ejemplo, en el caso de clases heredadas o submiembros el hacer referencia a sus clases base para poder, ya sea ampliar un tema o consultar el detalle de alguna implementación en particular, la etiqueta <seealso> nos ayuda a hacer referencia a una clase o namespace ya existente, el cual es especificado en su parámetro cref

<seealso> es utilizada dentro de la etiqueta <summary>

 

En el ejemplo hacemos referencia al NameSpace System.Data debido a que el valor de retorno hace referencia a un DataTable, el cual, pertenece a dicho NameSpace.

///<seealso cref="System.Data"/>

Resultado

<Exception>

Especifica las excepciones en las cuales el método puede incurrir

 

En el ejemplo hacemos referencia a la exepción System.ArgumentOutOfRangeException si es que el parametro "NumMaxReg" es mayor a 1000

///<exception cref="System.ArgumentOutOfRangeException">NumMaxReg es mayor a 1000</exception>

Resultado

<Permmision>

Especifica los permisos necesarios que se deben de cumplir para poder utilizar el método.

///<permission cref="System.Security.Permissions.FileIOPermission">Debe de tener permisos de escritura en la ruta especificada</permission>

Resultado

<Value>

En el caso de la propiedades, éste elemento proporciona una descripción del valor que se esta estableciendo o recuperando.

///<summary>             /// Obtiene el numero de cliente.             ///</summary>             ///<value>Numero de cliente especificado</value>

Resultado

 

* El compilador verificara la existencia del miembro.

Conclusión.

La documentación que incluye .Net proporciona un excelente mecanismo para realizar la documentación de nuestro código, aunque no solo basta documentarlo, si bien, nos enfocamos únicamente en explicar las etiquetas utilizadas, tambien es necesario realizar la generación de la documentación correspondiente en un formato más entendible, ésta funcionalidad la obtendremos gracias a NDoc del cual hablaremos en una segunda parte de éste articulo.

 

---

Espacios de nombres usados en el código de este artículo:

No se utiliza ningún espacio de nombres en particular.

Fichero con el código de ejemplo: neo_mx_DocumentacionCSharp.zip - 15 KB