Doxygen /ˈdɑːksiɡən/ és un generador de documentació, una eina per escriure documentació de referència del programari. La documentació és escrita dins del codi. D'aquesta manera, és relativament fàcil de mantenir actualitzada la documentació. Doxygen enllaça la documentació i el codi, de manera que el lector d'un document fàcilment pot referir al codi real.
Doxygen és programari lliure, alliberat sota els termes de la Llicència Pública General de GNU.
Disseny
Com Javadoc, Doxygen extreu documentació dels comentaris als arxius font. A més de la sintaxi pròpia de Javadoc, Doxygen suporta les etiquetes utilitzades en el Qt toolkit i pot generar sortida en HyperText Markup Language (HTML) així com Microsoft Compiled HTML Help (CHM), Format de Text Ric (RTF), Format de Document Portàtil (PDF), LaTeX, Postdata o pàgines de manual.
Usos
La llista de llenguatges de programació suportats per Doxygen inclou C, C++, C♯, Fortran, IDL, Java, Objective-C, Perl, PHP, Python, Tcl, VHDL i altres.
Es pot executar damunt la majoria de sistemes semblants a Unix, Mac OS X i Windows.
La primera versió de Doxygen es va basar en el codi d'una versió primerenca de DOC++ (desenvolupat per Roland Wunderling i Malte Zöckler a Zuse Institut Berlín); més tard, el codi de Doxygen va ser reescrit per Dimitri van Heesch.
Codi d'exemple
La sintaxi genèrica de comentaris de documentació és començar un comentari amb un asterisc extra després del delimitador de comentari '/':
/** <A short one line description> <Longer description> <May span multiple lines or paragraphs as needed> @param Description of method's or function's input parameter @param... @return Description of the return value * /
Malgrat que a molts programadors els agrada marcar l'inici de cada línia amb espai-asterisc-espai, de la manera següent:
/** * <A short one line description> * * <Longer description> * <May span multiple lines or paragraphs as needed> * * @param Description of method's or function's input parameter * @param... * @return Description of the return value */
Molts programadors eviten utilitzar comentaris d'estil C i en comptes d'això utilitzar comentaris de línia estil C++. Doxygen accepta comentaris amb una barra addicional com comentaris Doxygen.
/// <A short one line description> /// /// <Longer description> /// <May span multiple lines or paragraphs as needed> /// /// @param Description of method's or function's input parameter /// @param... /// @return Description of the return value
El següent il·lustra com un arxiu font en C++ pot ser documentat.
/** * @file * @author John Doe <jdoe@example.com> * @version 1.0 * * @section LICENSE * * This program is free software; you can redistribute it and/or * modify it under the terms of the GNU General Public License as * published by the Free Software Foundation; either version 2 of * the License, or (at your option) any later version. * * This program is distributed in the hope that it will be useful, but * WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU * General Public License for more details at * https://www.gnu.org/copyleft/gpl.html * * @section DESCRIPTION * * The time class represents a moment of time. */ class Time { public: /** * Constructor that sets the time to a given value. * * @param timemillis Number of milliseconds * passed since Jan 1, 1970. */ Time (int timemillis) { // the code } /** * Get the current time. * * @return A time object set to the current time. */ static Time now () { // the code } };
Una aproximació alternativa per documentar els paràmetres és mostrat a sota. Produirà la mateixa documentació.
/** * Constructor that sets the time to a given value. */ Time (int timemillis ///< Number of milliseconds passed since Jan 1, 1970.> ) { // the code }
L'ús d'un llenguatge de marques més ric també és possible. Per exemple, es poden afegir equacions fent servir LaTeX:
/** * * An inline equation @f$ e^{\pi i}+1 = 0 @f$ * * A displayed equation: @f[ e^{\pi i}+1 = 0 @f] * */