doxygenKomma igång med doxygen
Anmärkningar
Det här avsnittet ger en översikt över vad doxygen är och varför en utvecklare kanske vill använda den.
Det bör också nämna alla stora ämnen inom doxygen och länka till relaterade ämnen. Eftersom dokumentationen för doxygen är ny kan du behöva skapa initialversioner av relaterade ämnen.
Kommentera din kod
Det finns flera sätt att markera ett kommentarblock som en detaljerad beskrivning, så att detta kommentarblock analyseras av Doxygen och läggs till som en beskrivning av följande kodelement i dokumentationen. De första och vanligaste är kommentarer i C-stil med en extra asterisk i kommentarsstartsekvensen, t.ex.
/**
* … text …
*/
int dummy_var;
Nästa alternativ är att använda Qt-stilen och lägga till ett utropstecken (!) Efter öppningssekvensen för ett kommentarblock i C-stil:
/*!
* … text …
*/
void foo(void);
Ett tredje alternativ är att använda ett block med minst två C ++ kommentarrader, där varje rad börjar med ett extra snedstreck eller ett utropstecken:
///
/// ... text ...
///
eller
//!
//! ... text ...
//!
Vissa människor vill synliggöra sina kommentarblock i dokumentationen. För detta ändamål kan du använda följande:
/********************************************//**
* ... text
***********************************************/
Notera de två snedstreckna för att avsluta det normala kommentarblocket och starta ett speciellt kommentarblock.
/////////////////////////////////////////////////
/// ... text ...
/////////////////////////////////////////////////
För att strukturera och smälta den genererade dokumentationen, ger Doxygen ett stort antal (> 170) specialkommandon. Alla kommandon i dokumentationen börjar med ett backslash () eller ett at-sign (@).
Till exempel
/**
* \brief A brief description in one short sentence.
*/
är ekvivalent med
/**
* @brief A brief description in one short sentence.
*/
För den korta beskrivningen finns det också flera möjligheter:
Man kan använda kommandot \brief med ett av ovanstående kommentarblock. Detta kommando slutar i slutet av ett stycke, så den detaljerade beskrivningen följer efter en tom rad.
/** \brief Brief description.
* Brief description continued.
*
* Detailed description starts here.
*/
Om JAVADOC_AUTOBRIEF är inställt på YES i konfigurationsfilen, startar kommentarblocken i JavaDoc-stil automatiskt en kort beskrivning som slutar vid den första punkten följt av ett mellanslag eller en ny rad.
/// Brief description which ends at this dot. Details follow
/// here.
Och slutligen här ett exempel för en fullständig dokumentation av en funktion med doxygen:
/**
* \brief The function bar.
*
* \details This function does something which is doing nothing. So this text
* is totally senseless and you really do not need to read this,
* because this text is basically saying nothing.
*
* \note This text shall only show you, how such a \"note\" section
* is looking. There is nothing which really needs your notice,
* so you do not really need to read this section.
*
* \param[in] a Description of parameter a.
* \param[out] b Description of the parameter b.
* \param[in,out] c Description of the parameter c.
*
* \return The error return code of the function.
*
* \retval ERR_SUCCESS The function is successfully executed
* \retval ERR_FAILURE An error occurred
*/
errcode_t bar(int a, int b, int c)
{
/** More detailed description inside the code */
}
källa och mer information på Doxygen-hemsidan
Installation eller installation
Detaljerade instruktioner för att få doxygen inställd eller installerad.
