[C/C++] Doxygen e documentazione del codice sorgente

[bako]

Ho visto la pillola , 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

[andbin]

Originariamente inviato da bako
Ho visto la pillola , 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

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]

Originariamente inviato da andbin
..

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

[bako]

problema: è ù e i caratteri accentati non vengono visualizzati corretamente.. come posso fare?
ho scritto il codice con gedit..

[bako]

altra cosa, se non ho paramteri lo metto il tag? e se restituisco un void?

[andbin]

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]

Originariamente inviato da bako
problema: è ù e i caratteri accentati non vengono visualizzati corretamente.. come posso fare?
ho scritto il codice con gedit..

La documentazione di doxygen è molto chiara in questo caso. Vedere: HTML Commands.

Come ben spiega, puoi usare le entità HTML à é ecc...

[andbin]

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]

Originariamente inviato da andbin
La documentazione di doxygen è molto chiara in questo caso. Vedere: HTML Commands.

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

[andbin]

Originariamente inviato da bako
quindi devo documentare il codice c con i tag html? funzionale come cosa..

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.