Breve manual de Doxygen José Daniel Franco Barrios Grupo 10
Índice - Instalación o Descarga --------- p. 3 o Instalación en Windows y Linux --------- p. 3 - Utilidad --------- p. 4-7 o Listas --------- p. 6 o Grupos --------- p. 7 - Buenas prácticas --------- p.8
Instalación Descarga La instalación de Doxygen no presenta ninguna dificultad. La sección de descargas de la web oficial da opción a cinco descargas, cada una de ellas disponible a través de ftp y http. - La primera opción de descarga es el código fuente. - La segunda opción es la versión para Linux, válida para arquitecturas x86-64, y que incluye la versión HTML del manual, pero no la interfaz gráfica. - La tercera opción es un archivo ejecutable, un instalador para Windows XP, Vista y 7, hecha para 32 bits, pero válida para 64 bits también. Esta versión sí incluye la interfaz gráfica. Aparte del instalador, también da opción (dentro de la descripción de la descarga) a descargar los archivos en un zip. - Las opciones cuarta y quinta son imágenes de disco que tienen como objetivo Mac OS X (10.6/10.5 la primera y 10.4 la segunda). También contienen la interfaz gráfica. Instalador para Windows Una vez descargado, la instalación no tiene ningún tipo de complicación. En el manual de Doxygen se recomienda instalar GraphViz, que sirve para hacer mejores diagramas. Para crear archivos HTML comprimidos, es necesaria la Microsoft HTML help workshop. Para crear archivos Qt comprimidos, es necesario descargar Qt. Para generar PDFs o usar fórmulas científicas, será necesario tener LaTeX y Ghostscript. Distribución binaria en Unix Una vez descargada la distribución binaria (a diferencia del fuente, que hay que compilar), se debe escribir:./configure make install Los archivos son instalados por defecto en /usr/local/bin
Utilidad Para empezar, hablaremos sobre los comentarios. Existen varias formas de escribir comentarios compatibles con Doxygen: - Estilo JavaDoc: - Estilo Qt: /** * texto * texto - Al menos dos líneas de comentario de C++, añadiendo una barra o exlamación a cada línea: /// /// texto /// Ó //! //! texto //! - Para hacerlo más visible: //////////////////////////////////////////////// /// texto //////////////////////////////////////////////// Para la descripción breve también existen varias posibilidades, pero una de las más sencillas, tanto al escribir como al leerla, sería: //! Una descripción breve Una descripción más elaborada.
Teniendo la opción JAVADOC_AUTOBRIEF activada, también se podría emplear la siguiente forma, teniendo en cuenta que lo que va antes del primer punto es la descripción breve: /** * Una descripción breve. Y a partir de aquí una descripción más completa. Para poner comentarios después de la parte comentada, en lugar de antes (ya sea una clase, una variable ), es necesario añadir un símbolo < en el bloque de comentarios. También sirve para parámetros de una función. Por ejemplo, para una variable sería: int var; < Descripción de la variable ó int var; /**< Descripción de la variable ó int var; //!< Descripción de la variable Al documentar un método, para nombrar los parámetros de entrada se utiliza la etiqueta @param, y @return para lo que devuelve el método. * Texto de descripción del método * @param Parámetro de entrada * @return Retorno Así mismo se pueden usar las etiquetas @Author (para identificar al autor), @date (para la fecha), e incluso @brief (para la descripción breve, si no se usan los métodos anteriores). En caso de dejar algo por hacer, se puede emplear la etiqueta \todo {descripción de lo que se deja por hacer}, para añadirlo a la lista de tareas.
Listas También se pueden incluir listas. Para ello, se emplean guiones alineados en colmna: * Una lista de ejemplo: * - Ejemplo 1 * -# Sub-ejemplo 1 * -# Sub-ejemplo 2 * - Ejemplo 2 * * Resto del texto Se pueden crear listas anidadas, como se muestra, y si se añade una almohadilla (#) después del guion, la lista pasa a ser numerada. Quedaría así: Una lista de ejemplo: - Ejemplo 1 a. Sub-ejemplo 1 b. Sub-ejemplo 2 - Ejemplo 2 Resto del texto También se pueden usar etiquetas HTML: * Una lista de ejemplo: * <ul> * <li> Ejemplo 1 * <ol> * <li> Sub-ejemplo 1 * <li> Sub-ejemplo 2 * </ol> * <li> Ejemplo 2 * </ul>
Grupos Doxygen tiene 3 herramientas para dividir la documentación en grupos. El primero de ellos funciona a nivel global, creando una nueva página para cada grupo. Estos son los módulos ; el segundo funciona con una lista de miembros, y se le conoce como grupos de miembros ; el tercero es para páginas, y se conoce como subpaginar. Con los módulos se puede documentar tanto un grupo completo, como cada miembro individualmente. Los miembros de un grupo pueden ser archivos, clases, variables, funciones.. Los grupos pueden ser anidados también. /** \addtogroup <label> * @{... /** @} Los grupos de miembros se utilizan, por ejemplo, cuando una clase tiene demasiados miembros y es deseable agruparlos. Un grupo de miembros se define por: ///@{... ///@} Ó /**@{... /**@} Antes de estos bloques se puede poner otro bloque separado, con la propiedad @name, para dar nombre al grupo. Para especificar a qué grupo corresponde la documentación de una clase, se debe utilizar la etiqueta \ingroup.
Buenas prácticas - Todos los comentarios deben ser frases bien formadas y con gramática y puntuación correctas. - Las frases deben estar separadas por un solo espacio. - Los comentarios y los nombres de las variables deben estar en inglés (de Estados Unidos). - Sólo se usan palabras completamente en mayúsculas al hacer referencia a constantes. - La longitud máxima de una línea de comentario debe ser de 80 caracteres, haciendo un salto de línea en caso de tener que superar esa cantidad. - Usar siempre el mismo tipo de bloque para comentarios dentro del mismo proyecto. - Emplear comentarios de líneas, no sólo para clases y métodos, siempre que éstas lo requieran por su complejidad. - Emplear el menor número de etiquetas posible, para mantener limpio y legible el código. Así mismo, emplear frases lo más escuetas (aunque descriptivas) posible. - Tener cuidado al comentar para no crear confusión en lugar de explicar.