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