Introducción a C#
Por Nacho Cabanes, versión 0.93 de 16-abr-2010


(Nota: Estás viendo una versión del curso antigua, creada en 2009. Es recomendable que sigas la versión 2015, mucho más actualizada, con contenidos más detallados, más ejemplos y más ejercicios propuestos)

11.4.2. Generación de documentación a partir del código fuente.

Conocemos los comentarios de bloque (/* hasta */) y los comentarios hasta final de línea (a partir de una doble barra // ).

Pero en algunos lenguajes modernos, como Java y C#, existe una posibilidad adicional que puede resultar muy útil: usar comentarios que nos ayuden a crear de forma automática cierta documentación del programa.

Esta documentación típicamente será una serie páginas HTML enlazadas, o bien varios ficheros XML.

Por ejemplo, la herramienta (gratuita) Doxygen genera páginas como ésta a partir de un fuente en C#:

La forma de conseguirlo es empleando otros dos tipos de comentarios: comentarios de documentación en bloque (desde /** hasta */) y los comentarios de documentación hasta final de línea (a partir de una triple barra /// ).

Lo habitual es que estos tipos de comentarios se utilicen al principio de cada clase y de cada método, así:

/**
       *   Personaje: uno de los tipos de elementos graficos del juego
       *  
       *       @see ElemGrafico Juego
       *       @author 1-DAI 2008/09
       */
 
public class Personaje : ElemGrafico
{
 
  // Mueve el personaje a la derecha, si es posible (sin obstáculos)  
  public void MoverDerecha() {
    (...)
  }
 
  (...)
 
  /// Animación cuando el personaje muere: ambulancia, etc.
  public void Morir(){
    (...)
  }
 
} 
 

Además, es habitual que tengamos a nuestra disposición ciertas "palabras reservadas" para poder afinar la documentación, como @returns, que da información sobre el valor que devuelve una función, o como @see, para detallar qué otras clases de nuestro programa están relacionadas con la actual.

Así, comparando el fuente anterior y la documentación que se genera a partir de él, podemos ver que:

En el lenguaje Java, documentación como esta se puede crear con la herramienta JavaDoc, que es parte de la distribución "oficial" del lenguaje. En cambio, en C#, la herramienta estándar genera documentación en formato XML, que puede resultar menos legible, pero se pueden emplear alternativas gratuitas como Doxygen.