urriellu.net => Artículos => Software => Documentación en C#

En C# puedes escribir comentarios de una línea empezando por "//" o de varias líneas escribiendo entre "/*" y "*/". No hace falta poner asterisco al principio de cada línea, pero Visual Studio lo hace automáticamente y además queda mejor delimitado el comentario.

cvl-es.cs, 6 líneas      [descargar]

  1. //comentario
  2. int a = 1; //otro comentario
  3. /* comentario
  4. * de varias
  5. * líneas */
  6. int b = a;
  7.  

Pero lo realmente interesante es la posibilidad de documentar el código directamente. Es decir, escribir comentarios bien estructurados en XML y que éstos aparezcan como ayudas al autocompletar el nombre o parámetros de la clase, objeto, variable, etc y además también se pueda generar la propia documentación del programa basada exclusivamente en estos comentarios.

Todas las etiquetas son opcionales. Aquí solo se muestran unas pocas.

Documentar clases

cls-es.cs, 11 líneas      [descargar]

  1. ///<summary>
  2. ///Clase principal de la aplicación.
  3. ///</summary>
  4. ///<remarks>
  5. ///Lee archivos de configuración y crea los hilos que ejecutan el resto del programa.
  6. ///</remarks>
  7. class CApp {
  8.     static void Main(string[] args) {
  9.         ...
  10.     }
  11. }
  12.  

Entre las etiquetas <summary> y </summary> ponemos la descripción o resumen de la clase. Las etiquetas <remarks> y </remarks> las usamos para comentarios especiales, no se verán en el autocompletado pero sí en la documentación.

Documentar miembros

miem-es.cs, 10 líneas      [descargar]

  1. class CApp2 {
  2.     ///<summary>
  3.     ///Variable que almacena el número de reintentos al acceder a un archivo.
  4.     ///</summary>
  5.     ///<remarks>
  6.     ///Puede ser modificada en cualquier momento.
  7.     ///</remarks>
  8.     int var = 1;
  9.     ...
  10. }
  11.  

El sistema es idéntico al usado para clases.

Documentar métodos/funciones

met-es.cs, 14 líneas      [descargar]

  1. ///<summary>
  2. ///Lee la configuración de la aplicación desde el disco.
  3. ///</summary>
  4. ///<return>
  5. ///Devuelve true si la configuración fue leida. Si hubo algún error se devuelve false.
  6. ///</return>
  7. ///<param name="archivo">
  8. ///Ruta del archivo en disco a leer.
  9. ///</param>
  10. public bool LeeConfig(string archivo) {
  11.     bool c = false;
  12.     ...
  13.     return c;
  14. }
  15.  

Entre las etiquetas <return> y </return> se explica el valor devuelto por la función, y las etiquetas <param> se utilizan para describir cada uno de los parámetros del método/función.

Generar documentación

A parte de las ayudas al autocompletado que aparecen automaticamente en Visual Studio, SharpDevelop y MonoDevelop al documentar el código, también se pueden generar archivos de documentación. En Windows, usando la implementación del .NET Framework hecha por Microsoft, se utiliza el siguiente comando:

C:\>csc /doc:Documentacion.xml Programa.cs

En sistemas Unix con Mono instalado se utiliza:

mcs -doc:Documentacion.xml Programa.cs

Y en Windows con Mono instalado:

C:\>mcs /doc:Documentacion.xml Programa.cs

Documentando automáticamente

Existe un Add-in para MS Visual Studio 2003 y 2005, GhostDoc, que permite con una simple combinación de teclas generar los comentarios de documentación basados en lo que se esté intentando comentar (una clase, método, variable...).