PDA

Visualizza la versione completa : [C/C++] Doxygen e documentazione del codice sorgente


bako
19-05-2006, 13:40
Ho visto la pillola (http://forum.html.it/forum/showthread.php?s=&threadid=654765&highlight=Doxygen) , ma il topic Ŕ chiuso.
allora, per il c, se non ho le classi, come faccio?
devo metter /file nomefile.c
e poi per tutte le funzioni
/fn nome(a b c)
/param
/return
tutto questo va fatto per tutte le funzioni e messo in un unico file dentro un
/**
*/
??
posso fare un file esterno per mettere tutto quella cosa?
grazie :ciauz:

andbin
19-05-2006, 14:41
Originariamente inviato da bako
Ho visto la pillola (http://forum.html.it/forum/showthread.php?s=&threadid=654765&highlight=Doxygen) , ma il topic Ŕ chiuso.
allora, per il c, se non ho le classi, come faccio?
devo metter /file nomefile.c
e poi per tutte le funzioni
/fn nome(a b c)
/param
/return
tutto questo va fatto per tutte le funzioni e messo in un unico file dentro un
/**
*/
??
posso fare un file esterno per mettere tutto quella cosa?
grazie :ciauz: Allora, per prima cosa, a prescindere dal sistema di documentazione usato (Doxygen, Javadoc, o qualunque altro), consiglio vivamente di mettere sempre tutta la documentazione all'interno del file sorgente.
Doxygen in effetti consente di inserire la documentazione anche in un file esterno al sorgente (usando poi dei comandi speciali che permettono di indicare cosa si sta documentando). Io per˛, personalmente, lo sconsiglio.

Se hai bisogno di un esempio (minimale/stupido) su come impostare i commenti, ti posto questo:

/*! \file util.c
*
* \brief Utility functions.
*
* A set of utility functions.
*
* \version 1.0
* \date May 19, 2006
* \author andbin
*/


/*! \brief Swaps two integers.
*
* This function swaps the value of two integers.
*
* \param pval1 Pointer to first integer value
* \param pval2 Pointer to second integer value
*
* \return Returns <code>1</code> if the function succeeds,
* <code>0</code> if the function fails.
*/
int swap_int (int *pval1, int *pval2)
{
int t;

if (pval1 == NULL || pval2 == NULL)
return 0;

if (pval1 == pval2)
return 1;

t = *pval1;
*pval1 = *pval2;
*pval2 = t;

return 1;
}
Nell'esempio sopra ho usato lo stile "QT" (/*!).

bako
19-05-2006, 17:11
Originariamente inviato da andbin
..

se ho pi¨ file? ripeto l'operazione per tutti i file giusto?

bako
19-05-2006, 19:57
problema: Ŕ ¨ e i caratteri accentati non vengono visualizzati corretamente.. come posso fare?
ho scritto il codice con gedit..
:ciauz:

bako
19-05-2006, 21:00
altra cosa, se non ho paramteri lo metto il tag? e se restituisco un void?

andbin
20-05-2006, 10:52
Originariamente inviato da bako
se ho pi¨ file? ripeto l'operazione per tutti i file giusto? Beh certo! Ogni sorgente avrÓ la "sua" documentazione.

andbin
20-05-2006, 11:01
Originariamente inviato da bako
problema: Ŕ ¨ e i caratteri accentati non vengono visualizzati corretamente.. come posso fare?
ho scritto il codice con gedit..
:ciauz: La documentazione di doxygen Ŕ molto chiara in questo caso. Vedere: HTML Commands (http://www.stack.nl/~dimitri/doxygen/htmlcmds.html).

Come ben spiega, puoi usare le entitÓ HTML &agrave; &eacute; ecc...

andbin
20-05-2006, 11:05
Originariamente inviato da bako
se non ho paramteri lo metto il tag? No.


Originariamente inviato da bako
e se restituisco un void? Non sei obbligato a mettere un \return.
Tuttavia, per maggior chiarezza nella documentazione, potresti mettere una cosa del tipo:
\return This function does not return a value.

bako
20-05-2006, 12:58
Originariamente inviato da andbin
La documentazione di doxygen Ŕ molto chiara in questo caso. Vedere: HTML Commands (http://www.stack.nl/~dimitri/doxygen/htmlcmds.html).

quindi devo documentare il codice c con i tag html? funzionale come cosa.. :incupito:

andbin
20-05-2006, 14:35
Originariamente inviato da bako
quindi devo documentare il codice c con i tag html? funzionale come cosa.. :incupito: Beh comunque Ŕ una cosa che vale, credo, un po' per tutti i sistemi di documentazione del codice. Doxygen e Javadoc consentono di usare tag e entitÓ HTML. Altri sistemi di documentazione ... non lo so.
Tieni presente che l'output "tipico" della documentazione generata dai sorgenti Ŕ in HTML.

Loading