Doxygen
  | |
 Captura de pantalla de la versió 1.8.1 | |
| Tipus | generador de documentació i programari lliure |
|---|---|
| Versió inicial | 26 octubre 1997 |
| Versió estable | 1.12.0 (7 agost 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 /ˈ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.
Doxygen és programari lliure, alliberat sota els termes de la Llicència Pública General de GNU.
Disseny
[modifica]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
[modifica]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.[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]