Doxygen ( / d ɒ k s i dʒ ən / DOK -ver-jən ) [3] es un generador de documentación [4] [5] [6] [7] y el análisis estático herramienta para el software de árboles de código fuente . Cuando se utiliza como generador de documentación, Doxygen extrae información de comentarios con formato especial dentro del código. Cuando se usa para análisis, Doxygen usa su árbol de análisis para generar diagramas y gráficos de la estructura del código. Doxygen puede realizar referencias cruzadas de documentación y código, de modo que el lector de un documento pueda consultar fácilmente el código real.
Desarrollador (es) | Dimitri van Heesch |
---|---|
Versión inicial | 26 de octubre de 1997 [1] |
Lanzamiento estable | 1.9.1 [2] / 8 de enero de 2021 |
Repositorio | |
Escrito en | C ++ |
Sistema operativo | Multiplataforma |
Tipo | Generador de documentación |
Licencia | GPLv2 |
Sitio web | www |
Doxygen es un software gratuito , publicado bajo los términos de la GNU General Public License versión 2 (GPLv2).
Diseño
Al igual que Javadoc , Doxygen extrae la documentación de los comentarios del archivo fuente. Además de la sintaxis de Javadoc, Doxygen es compatible con las etiquetas de documentación utilizadas en el kit de herramientas de Qt y puede generar resultados en HyperText Markup Language ( HTML ), así como en Microsoft Compiled HTML Help (CHM), Rich Text Format (RTF), Portable Document Format (PDF), LaTeX , PostScript o páginas man .
Usos
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. . [14] Se pueden admitir otros idiomas con código adicional.
Doxygen se ejecuta en la mayoría de los sistemas similares a 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, Dimitri van Heesch reescribió el código de Doxygen.
Doxygen tiene soporte incorporado para generar diagramas de herencia para clases de C ++. Para diagramas y gráficos más avanzados, Doxygen puede utilizar la herramienta "punto" de Graphviz . [15]
Código de ejemplo
La sintaxis genérica de los comentarios de documentación es comenzar un comentario con un asterisco adicional después del delimitador de comentario principal '/ *':
/ ** ón> @param Descripción del parámetro de entrada del método o función @param ... @return Descripción del valor de retorno * /
A muchos programadores les gusta marcar el inicio de cada línea con espacio-asterisco-espacio, como sigue, pero eso no es necesario.
/ ** * breve de una línea> * * ón>* * * @param Descripción del parámetro de entrada del método o función * @param ... * @return Descripción de el valor de retorno * /
Muchos programadores evitan usar comentarios de estilo C y en su lugar usan comentarios de una sola línea de estilo C ++. Doxygen acepta comentarios con barra adicional como comentarios de Doxygen.
/// breve de una línea> /// /// ón>/// /// /// @param Descripción del parámetro de entrada del método o función // / @param ... /// @return Descripción del valor de retorno
A continuación se ilustra cómo se puede documentar un archivo fuente C ++ .
/ ** * @file * @author John Doe @example.com>* @version 1.0 * * @section LICENCIA * * Este programa es software gratuito; puede redistribuirlo y / o * modificarlo según los términos de la Licencia Pública General GNU como * publicada por la Free Software Foundation; ya sea la versión 2 de * la Licencia, o (a su elección) cualquier versión posterior. * * Este programa se distribuye con la esperanza de que sea útil, pero * SIN NINGUNA GARANTÍA; incluso sin la garantía implícita de * COMERCIABILIDAD o APTITUD PARA UN PROPÓSITO PARTICULAR. Consulte la Licencia Pública General GNU * para obtener más detalles en * https://www.gnu.org/copyleft/gpl.html * * @sección DESCRIPCIÓN * * La clase de tiempo representa un momento de tiempo. * /class Time { publico : / ** * Constructor que establece el tiempo en un valor dado. * * @param timemillis es un número de milisegundos * transcurridos desde el 1 de enero de 1970. * / Time ( int timemillis ) { // el código } / ** * Obtiene la hora actual. * * @return Un objeto de hora establecido en la hora actual. * / static Time now () { // el código } };
A continuación se muestra un enfoque alternativo para documentar los parámetros. Producirá la misma documentación.
/ ** * Constructor que establece el tiempo en un valor dado. * / Time ( int timemillis /// úmero> ) { // el código }
También es posible un marcado más rico. Por ejemplo, agregue ecuaciones usando 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] * * /
Fuente y desarrollo de oxígeno
Las fuentes de Doxygen están actualmente alojadas en GitHub , donde el desarrollador principal, Dimitri van Heesch, contribuye con el nombre de usuario "doxygen". [16] Doxygen está escrito en C ++ y comprende más de 300.000 líneas de código fuente . Para el análisis léxico , la herramienta estándar Lex (o su reemplazo Flex) se ejecuta en más de 35.000 líneas de script lex. La herramienta de análisis Yacc (o su reemplazo Bison) también se usa, pero solo para tareas menores; la mayor parte del análisis del lenguaje se realiza mediante código nativo C ++. El proceso de compilación se basa en CMake y también involucra algunos scripts de Python.
Ver también
- Comparación de generadores de documentación
- Escritor de API
- Análisis de programa estático
Referencias
- ^ ANUNCIO: doxygen 0.1 Archivado el 4 de octubre de 2011, en Wayback Machine , Anunciando: la primera versión de Doxygen, un sistema de documentación C ++. , De: Dimitri van Heesch, Fecha: Domingo, 26 de octubre de 1997, Archivo de interés de Qt
- ^ http://www.doxygen.nl/manual/changelog.html
- ^ Preguntas frecuentes: ¿Cómo obtuvo el doxygen su nombre?
- ↑ Perkel, Jeffrey M. (22 de noviembre de 2015). "Get With the Program: consejos de bricolaje para agregar codificación a su arsenal de análisis" . El científico ( Revista ). El científico.
- ^ Sabin, Mihaela (22 de noviembre de 2015). "Doxygen" . OpenComputing ( Wiki ). Universidad de New Hampshire. Archivado desde el original el 23 de noviembre de 2015.
- ^ "Doxygen" . Directorio de software libre ( Wiki ). 2015-11-22.
- ^ "Documentación" . Código Rosetta ( Wiki ). 2015-11-22.
- ^ "Documentación: C" . Código Rosetta ( Wiki ). 2015-11-22.
- ^ "Documentación: Objective-C" . Código Rosetta ( Wiki ). 2015-11-22.
- ^ http://search.cpan.org/perldoc?Doxygen%3A%3AFilter%3A%3APerl
- ^ http://www.doxygen.nl/manual/starting.html
- ^ "Herramientas de generación automática de documentación de la API de Python" . wiki de python.org ( Wiki ). 2015-11-22.
- ^ https://pypi.python.org/pypi/doxypypy/
- ^ http://www.doxygen.nl/manual/starting.html
- ^ http://www.doxygen.nl/manual/diagrams.html
- ^ https://github.com/doxygen/doxygen
enlaces externos
- Página web oficial