Doxygen ( / ˈd ɒ k s i dʒ ən / DOK -see-jən ) [3] es un generador de documentación [4] [5] [6] [7] y una herramienta de análisis estático para árboles de código fuente de software . Cuando se utiliza como generador de documentación, Doxygen extrae información de comentarios especialmente formateados dentro del código. Cuando se utiliza para análisis, Doxygen utiliza su árbol de análisis para generar diagramas y gráficos de la estructura del código. Doxygen puede realizar referencias cruzadas entre documentación y código, de modo que el lector de un documento pueda consultar fácilmente el código real.
Doxygen es software libre , publicado bajo los términos de la Licencia Pública General GNU versión 2 (GPLv2).
Al igual que Javadoc , Doxygen extrae la documentación de los comentarios de los archivos fuente. Además de la sintaxis de Javadoc, Doxygen admite las etiquetas de documentación utilizadas en el kit de herramientas Qt y puede generar resultados en lenguaje de marcado de hipertexto ( HTML ), así como en Microsoft Compiled HTML Help (CHM), formato de texto enriquecido (RTF), formato de documento portátil (PDF), LaTeX , PostScript o páginas de manual .
Los lenguajes de programación compatibles con Doxygen incluyen C , [8] C++ , C# , D , Fortran , IDL , Java , Objective-C , [9] Perl , [10] PHP , [11] Python , [12] [13] y VHDL . [11] Se pueden admitir otros lenguajes con código adicional.
Doxygen se ejecuta en la mayoría de los sistemas tipo Unix , macOS y Windows .
La primera versión de Doxygen tomó prestado el código de una versión anterior de DOC++, desarrollada por Roland Wunderling y Malte Zöckler en el Zuse Institute de Berlín . Más tarde, el código de Doxygen fue reescrito por Dimitri van Heesch.
Doxygen tiene soporte integrado para generar diagramas de herencia para clases C++. Para diagramas y gráficos más avanzados, Doxygen puede utilizar la herramienta "punto" de Graphviz . [14]
La sintaxis genérica de los comentarios de la documentación es comenzar un comentario con un asterisco ( *) o un signo de exclamación ( !) adicional después del delimitador de comentario inicial ' /*':
/** <Una breve descripción de una línea><Descripción más larga> <Puede abarcar varias líneas o párrafos según sea necesario>@param someParameter Descripción del parámetro de entrada o salida del método o función @param ... @return Descripción del valor de retorno */Todos los comandos en la documentación comienzan con una barra invertida ( \) o un signo arroba ( @). [15]
A muchos programadores les gusta marcar el inicio de cada línea con espacio-asterisco-espacio, como se muestra a continuación, pero eso no es necesario.
/** * <Una descripción corta de una línea> * * <Descripción más larga> * <Puede abarcar varias líneas o párrafos según sea necesario> * * @param someParameter Descripción del parámetro de entrada o salida del método o función * @param ... * @return Descripción del valor de retorno */Muchos programadores evitan utilizar comentarios de estilo C y, en su lugar, utilizan comentarios de una sola línea de estilo C++. Doxygen acepta comentarios con una barra diagonal ( /) o un signo de exclamación ( !) adicionales como comentarios de Doxygen. [16]
/// <Una descripción corta de una línea > /// /// <Descripción más larga> /// <Puede abarcar varias líneas o párrafos según sea necesario> /// /// @param someParameter Descripción del parámetro de entrada o salida del método o función /// @param ... /// @return Descripción del valor de retorno//! <Una descripción breve de una línea> //! //! <Descripción más larga> //! <Puede abarcar varias líneas o párrafos según sea necesario> //! //! @param someParameter Descripción del parámetro de entrada o salida del método o función //! @param ... //! @return Descripción del valor de retornoA continuación se ilustra cómo se puede documentar un archivo fuente de C++.
/** * @file * @brief El archivo de encabezado de la clase Time. * @autor John Doe <[email protected]> * @versión 1.0 * @copyright CC BY-SA o GFDL. * @sa <a href="https://en.wikipedia.org/wiki/Doxygen/Wikipedia:Copyrights">Wikipedia:Copyrights - Wikipedia</a> *//** * La clase de tiempo representa un momento en el tiempo. * * @author John Doe */ class Time { public : /** * Constructor que establece la hora en un valor dado. * * @param timeMillis Un número de milisegundos transcurridos desde el 1 de enero de 1970. */ explicit Time ( long long timeMillis ) { // el código } /** * Obtener la hora actual. * * @return Un objeto de tiempo establecido en la hora actual. */ static Time now () { // el código } privado : long long m_timeMillis ; ///< Milisegundos transcurridos desde el 1 de enero de 1970. }; Para colocar la documentación después de los miembros, <se requiere un marcador adicional en el bloque de comentarios. [17]
A continuación se muestra un enfoque alternativo para documentar los parámetros, que generará la misma documentación.
/** * Constructor que establece la hora en un valor dado. */ explicit Time ( long long timeMillis /**< Un número de milisegundos transcurridos desde el 1 de enero de 1970. */ ) { // el código } /** * Constructor que establece la hora en un valor dado. */ explicit Time ( long long timeMillis ///< Un número de milisegundos transcurridos desde el 1 de enero de 1970. ) { // el código } También es posible utilizar un marcado más completo. Por ejemplo, se pueden añadir ecuaciones mediante comandos LaTeX :
/** * * Una ecuación en línea @f$ e^{\pi i}+1 = 0 @f$ * * Una ecuación mostrada: @f[ e^{\pi i}+1 = 0 @f] * */Las fuentes de Doxygen están actualmente alojadas en GitHub , donde el desarrollador principal, Dimitri van Heesch, contribuye bajo el nombre de usuario "doxygen". [18] Doxygen está escrito en C++ y consta de alrededor de 300.000 líneas de código fuente . Para el análisis léxico , se ejecuta la herramienta estándar Lex (o su reemplazo Flex) a través de aproximadamente 35.000 líneas de script lex. También se utiliza la herramienta de análisis Yacc (o su reemplazo Bison), pero solo para tareas menores; la mayor parte del análisis del lenguaje se realiza mediante código nativo de C++. El proceso de compilación se basa en CMake y también involucra algunos scripts de Python.
.svg/1280px-Free_and_open-source_software_logo_(2009).svg.png){kind=logo}