Iver's web place

Si bien es conocido que existe la manera de documentar el código desde C# con etiquetas XML, en la mayoría de los proyectos que he estado, pocas son las personas que realmente emplean esta herramienta.

Debido al escaso uso de documentación en el código, me dí a la tarea de realizar un pequeño extracto de información sobre las etiquetas que se pueden emplear y como generar la documentación de manera automática. Algunas de las etiquetas que se emplean son las siguientes:

summary: Su contenido se utiliza para indicar un resumen sobre el significado del elemento al que precede. Cada vez que en VS.NET se use el operador “.” para acceder a algún miembro de un objeto o tipo se usará esta información para mostrar sobre la pantalla del editor de texto un resumen acerca de su utilidad.

Ejemplo:



param: Permite documentar el significado de un parámetro de un método. En su propiedad name se indica el nombre del parámetro a documentar y en su contenido se describe su utilidad. Por ejemplo:

Al generarse la documentación se comprueba si el método documentado dispone de algún parámetro con el nombre indicado en name y, como ocurre con cref, si no fuese así se generaría un mensaje de aviso informando de ello.

returns: Permite documentar el significado del valor de retorno de un método, indicando como contenido suyo una descripción sobre el mismo. Por ejemplo:
El documento completo lo pueden descargar desde aquí. Dicho documento ha sido realizado a partir del trabajo generado y publicado por José Antonio González en su página http://www.josanguapo.com/.

Ventajas de emplear las etiquetas de documentación:

• Transmisión fácil / simple del conocimiento en el código.
• Generación de documentación técnica automatizada.
• Uso del intelisense de Visual Studio para conocer lo que hace internamente el código sin tener que verlo.

Ya hablaré en otro post sobre el archivo de salida para documentación técnica a partir del compilador o bien de herramientas externas.

Continuara ... =)