Doxygen
Doxygen /ˈdɑːksiɡən/[1] és un generador de documentació, una eina per escriure documentació de referència del programari.[2][3][4][5] 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.
  | |
 Captura de pantalla de la versió 1.8.1 | |
| Tipus | generador de documentació i programari lliure |
|---|---|
| Versió inicial | 26 octubre 1997 |
| Versió estable | 1.11.0 (20 maig 2024)
|
| Llicència | GNU GPL 2.0 |
| Característiques tècniques | |
| Sistema operatiu | Mac OS, Microsoft Windows i Unix-like |
| Escrit en | C++ |
| Biblioteca d'interfície d'usuari | Qt |
| Més informació | |
| Lloc web | doxygen.org (anglès) |
| Stack Exchange | Etiqueta |
| SourceForge | doxygen |
| Free Software Directory | Doxygen |
|
| |
 | |
Doxygen és programari lliure, alliberat sota els termes de la Llicència Pública General de GNU.
Disseny
modificaCom 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
modificaLa llista de llenguatges de programació suportats per Doxygen inclou C, C++, C♯, Fortran, IDL, Java, Objective-C, Perl, PHP, Python, Tcl, VHDL i altres.[6][7][8][9][10][11]
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
modifica
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]
*
*/
Referències
modifica- ↑ FAQ: How did doxygen get its name?
- ↑ Perkel, Jeffrey M. «Get With the Program: DIY tips for adding coding to your analysis arsenal». The Scientist, 22-11-2015.
- ↑ Sabin, Mihaela. «Doxygen». University of New Hampshire, 22-11-2015. Arxivat de l'original el 2015-11-23. [Consulta: 19 desembre 2015].
- ↑ «Doxygen», 22-11-2015.
- ↑ «Documentation», 22-11-2015.
- ↑ «Documentation: C», 22-11-2015.
- ↑ «Documentation: Objective-C», 22-11-2015.
- ↑ http://search.cpan.org/~jordan/Doxygen-Filter-Perl-1.62/lib/Doxygen/Filter/Perl.pm
- ↑ http://www.stack.nl/~dimitri/doxygen/starting.html
- ↑ «Automatic Python API documentation generation tools», 22-11-2015.
- ↑ https://pypi.python.org/pypi/doxypypy/
Enllaços externs
modifica| A Wikimedia Commons hi ha contingut multimèdia relatiu a: Doxygen |