header

Doxygen permite generar de forma simple la documentación de un proyecto, para esto los comentarios en el código deben seguir cierta estructura, luego mediante la herramienta se puede generar, por ejemplo, documentación en HTML o PDF.

Puedes revisar la siguiente presentación que contiene una explicación "más" detallada de Doxygen.

Tipo de documentación que se puede generar

  • HTML
  • Latex
  • RTF
  • MAN pages
  • XML
  • Experimentales: Autogen y PerlMod

Ejemplo de uso

Este ejemplo no cubre todo lo que se pueda documentar.

Documentar clase/función/método utilizando estilo JavaDoc

A continuación se muestra como documentar una clase, función o método. Notar que no todos los campos son obligatorios, en general se recomienda una descripción un autor y una versión. En caso de existir parámetros, retorno o tareas pendientes se utilizan los otros campos.

/**
 * @brief Descripción corta
 *
 * Descripción detallada
 * @param VARIABLE Descripción del parámetro que recibe la función
 * @return TIPO Lo que retorna la función
 * @todo Descripción de tareas pendientes para la función
 * @author Nombre del autor de la función
 * @version Versión de la función (ej: 2012-10-19)
 */

Para que se genere la documentación de un método la clase debe estár también documentada. En casos de archivos (que no corresponden a clases) se debe agregar la documentación para el archivo:

/**
 * @file basics.php
 * Archivo de funciones
 */

Generar configuración de doxygen

Ir al directorio del código fuente y ejecutar:

$ doxygen -g

Lo anterior generará un archivo Doxyfile el cual editamos para ajustar a nuestras necesidades.

Editar Doxyfile

Algunas opciones interesantes son:

  • PROJECT_NAME: Nombre del proyecto
  • PROJECT_NUMBER: Versión o revisión
  • PROJECT_BRIEF: Descripción corta
  • PROJECT_LOGO: Imagen de 200x55px
  • OUTPUT_DIRECTORY: Donde se guardará la documentación (sugerido: doc)
  • OUTPUT_LANGUAGE: Idioma de la documentación (sugerido: Spanish)
  • TAB_SIZE: Espacios que representarán una tabulación (sugerido: 4)
  • RECURSIVE: Procesar directorios de forma recursiva (sugerido: YES)
  • EXCLUDE: Directorios que se deben excluir
  • SOURCE_BROWSER: Generar árbol con el código fuente documentado (sugerido: YES)
  • INLINE_SOURCES: Mostrar código fuente de funciones o métodos (sugerido: NO)
  • REFERENCEDBYRELATION: Indicar ¿quién? utiliza el método o función (sugerido: YES)
  • REFERENCES_RELATION: Indicar ¿qué? funciones o métodos utiliza (sugerido: YES)
  • GENERATE_HTML: Si se quiere o no generar documentación en HTML (sugerido: YES)
  • GENERATE_LATEX: Si se quiere o no generar documentación en Latex (sugerido: NO)
  • HAVE_DOT: Se tiene el comando dot, que es parte de Graphviz (sugerido: YES)
  • CALL_GRAPH: Generar gráfico de llamadas entre los métodos, requiere HAVE_DOT=YES (sugerido: YES)

Generar documentación

$ doxygen Doxyfile
Última modificación de esta página fue el 2015-07-10 14:57:03