Generador de documentación : un programa o paquete de software que le permite obtener documentación destinada a programadores ( documentación API ) y/o para usuarios finales del sistema, de acuerdo con un código fuente especialmente comentado y, en algunos casos, módulos ejecutables (obtenidos en el salida del compilador ).
Normalmente, el generador analiza el código fuente del programa, destacando las construcciones sintácticas correspondientes a los objetos significativos del programa (tipos, clases y sus miembros/propiedades/métodos, procedimientos/funciones, etc.). El análisis también utiliza metainformación sobre los objetos del programa, presentados en forma de comentarios de documentación. En base a toda la información recopilada, la documentación preparada se forma, por regla general, en uno de los formatos generalmente aceptados: HTML , HTMLHelp , PDF , RTF y otros.
Un comentario de documento es un comentario con formato especial en un objeto de programa para que lo use un generador de documentación específico. La sintaxis de las construcciones utilizadas en los comentarios de la documentación depende del generador de documentación que se utilice .
Los comentarios de la documentación pueden contener información sobre el autor del código, describir el propósito del objeto del programa, el significado de los parámetros de entrada y salida para una función/procedimiento, ejemplos de uso, posibles excepciones y características de implementación.
Los comentarios de la documentación suelen tener el formato de comentarios de estilo C de varias líneas . En cada caso, el comentario debe ir antes del elemento documentado. El primer carácter de un comentario (y al comienzo de las líneas de comentario) debe ser *. Los bloques están separados por líneas en blanco.
Un ejemplo de un comentario documental en PHP :
/** * Nombre del objeto o descripción breve * * Descripción larga * * @descriptor_name value * @return data_type */| Lista de identificadores de phpDocumentor | ||
|---|---|---|
| descriptor | Descripción | Ejemplo |
| @author | Autor | /** * Archivo de muestra 2, inicio rápido de phpDocumentor * * Un archivo de la documentación de phpDocumentor * que demuestra cómo comentar. * @autor Greg Beaver <[email protected]> * @version 1.0 * @package sample * @subpackage classes */ |
| @version | Versión de código | |
| @package | Especifica el paquete al que pertenece el código. | |
| @subpackage | Especifica un subpaquete | |
| @global | Descripción de las variables globales | /** * DocBlock para una variable global * @global integer $GLOBALS['myvar'] seguido de una función con una variable global * o una variable global, en cuyo caso debe especificar su nombre * @name $myvar */ $ GLOBALES [ 'myvar' ] = 6 ; |
| @name | nombre, etiqueta | |
| @staticvar | Descripción de variables estáticas | /** * @staticvar integer $staticvar * @return devuelve un valor entero */ |
| @return | Descripción del valor de retorno | |
| @todo | Notas para su posterior implementación. | /** * DocBlock con listas anidadas * @todo Lista TODO simple * - item 1 * - item 2 * - item 3 * @todo Lista TODO anidada * <ol> * <li>item 1.0</li> * <li> elemento 2.0</li> * <ol> * <li>elemento 2.1</li> * <li>elemento 2.2</li> * </ol> * <li>elemento 3.0</li> * </ol> */ |
| @link | Enlace | /** * Este es un ejemplo de {@link http://www.example.com hipervínculo incrustado} */ |
| @deprecated (@deprec) | Descripción del bloque obsoleto | /** * @deprecated descripción * @deprec es un sinónimo de obsoleto */ |
| @example | Ejemplo | /** * @abstract * @access público o privado * @copyright nombre fecha * @example /path/to/example * @ignore * @internal información privada para especialistas * @param type [$varname] descripción del parámetro de entrada * @return tipo valor devuelto descripción * @ver otro elemento nombre (referencia) * @desde versión o fecha * @static */ |
| @see | Enlace a otro lugar en la documentación. | |
| Otros descriptores | ||
| @copyright • @license • @filesource • @category • @since • @abstract • @access • @example • @ignore • @internal • @static • @throws • @uses • @tutorial | ||
Un ejemplo de un comentario de documento para una función en un programa Java , destinado a ser utilizado por Javadoc :
/** * Comprueba si el movimiento es válido. * Por ejemplo, para establecer el movimiento e2-e4, escribe isValidMove(5,2,5,4); * @author John Doe * @param theFromFile La vertical donde está la forma (1=a, 8=h) * @param theFromRank La horizontal donde está la forma (1...8) * @param theToFile La vertical donde está la forma se realiza este movimiento (1=a, 8=h) * @param theToRank La horizontal de la celda a mover (1...8) * @return true si el movimiento es válido y false si no lo es */ boolean isValidMove ( int theFromFile , int theFromRank , int theToFile , int theToRank ) { . . . }Ejemplos para diferentes lenguajes y entornos de programación: