Tanto o más importante que tirarse horas programando una aplicación es su documentación, y debemos hacerlo aunque nosotros seamos los únicos que intervengamos en su desarrollo.
Algo que siempre digo en mis clases de programación es que a poco que compliquemos el código si no comentamos lo que estamos haciendo, en séis meses cuando toque hacer una siguiente versión no tendremos ni idea de lo que hace; y esto conlleva pasar más tiempo para hacer las modificaciones que necesitamos, que al final se traducen en dinero.
Doxygen es una de esas herramientas que nos hacen la vida más fácil, ya que analizará los comentarios de nuestros archivos fuente y generará un documento (html, latex…) con todas las clases, funciones, métodos, variables globales, definiciones, etc que contenga nuestro código; se generará un documento muy valioso para hacer futuras modificaciones.
Este programa tiene multitud de opciones y palabras clave que podemos ver en su documentación. Pero yo comentaré lo justo para empezar, ya que no queremos perder mucho tiempo y queremos empezar a documentar código. Hay muchos lenguajes soportados, pero tanto para C, C++, PHP y algunos otros podemos hacer comentarios con /* …. */ o //, pues bien, Doxygen leerá los comentarios que comiencen por /** (barra, asterisco, asterisco) o /// (tres barras). Lo que situemos como comentario será la descripción de la función, clase, método, o lo que sea que pongamos detrás; así como la descripción del propio fichero que pondremos como primer comentario al principio de nuestro código.
Para Doxygen existen algunas palabras clave como por ejemplo:
- @file : Especifica el propio fichero que editamos, útil para la descripción del fichero.
- @brief : Breve descripcion de la función, método, clase, variable… que estamos describiendo.
- @date : Fecha
- @author : Autor
- @version : Versión
- @param : Parámetro (en caso de funciones y métodos)
- @return : Valor de la salida (en caso de funciones y métodos)
Propongo un pequeño código en PHP que no hace nada, pero que se documentará bien:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 | <?php /** ****************************************************** * @file test.php * @brief Breve descripción * Pequeña documentación del archivo * @author Gaspar * @version 2.0 * @date Marzo 2010 * * *******************************************************/ /** * Variable global */ $var_global='VALOR'; /** Ahora me da por definir cosas */ define('defino_algo', 'DEFINICION'); /* * Description: Esta función algo hará * * @param $cadena * Esto es una cadena graciosa * @param $vector * Esto es un vestor gracioso * * @return string * Cadena resultante */ function estoyprobando($cadena, $vector) { } /** ****************************************************** * @brief Clase para hacer pruebas * ******************************************************/ class TestingPHP { /** ************************************************************* * @brief Constructor *************************************************************/ function __construct() { } /** ************************************************************* * @brief Metodo 1 * @param $par Primer parametro de entrada * * @return Genero una salida *************************************************************/ function metodo1($par) { } }; ?>; |
Para documentarlo con Doxygen, tendremos que hacer lo siguiente:
$ doxygen -g testing.cfg
Generaremos un archivo de configuración de la documentación de ejemplo, sólo tendremos que cambiar unas cuantas cosas para generar la documentación como nosotros queramos:
- PROJECT_NAME=Miproyecto (una sóla palabra)
- PROJECT_NUMBER=0.2 (la versión)
- OUTPUT_DIRECTORY=doc (Directorio donde irá la documentación)
- OUTPUT_LANGUAGE=Spanish (Queremos documentación en español
- EXTRACT_ALL= YES (Incluso lo que no esté documentado aparecerá en la documentación
- EXTRACT_PRIVATE=YES (Extraeremos los métodos públicos)
- EXTRACT_STATIC= YES (Extraeremos los métodos estáticos)
- RECURSIVE= YES (Extracción recursiva, incluiremos los subdirectorios)
- CREATE_SUBDIRS=YES (Creará subdirectorios a la hora de documentar, es importante si tenemos muchas líneas de código fuente (muchas funciones, clases, archivos….) ya que de otra forma situará todos los archivos de la salida en el mismo directorio, y pueden ser muchos.)
- FILE_PATTERNS = *.php3 *.php *.c *.cpp (Todas las extensiones de nuestros archivos fuente)
- PDF_HYPERLINKS= YES (Crearemos una salida LaTeX con enlaces que se exportarán a PDF)
- HAVE_DOT=YES (Crearemos mejores gráficos de clases)
Tras ello hacemos:
$ doxygen testing.cfg
Tendremos en el directorio doc toda la documentación de nuestra aplicación.
Foto: br1dotcom (Flickr)
Pingback: Bitacoras.com /
Pingback: Poesía binaria » Abbrev mode para EMACS (utiliza abreviaturas) /