Dove mettere i blocchi di commenti doxygen per una libreria interna - nei file H o CPP? [chiuso]

Il buon senso dice che i blocchi di commento di Doxygen devono essere inseriti nei file di intestazione dove si trovano le classi, le strutture, le enumerazioni, le funzioni e le dichiarazioni. Sono d'accordo sul fatto che questo sia un valido argomento per una libreria che deve essere distribuita senza la sua fonte (solo intestazioni e librerie con codice oggetto).

MA ... ho pensato all'approccio esattamente opposto quando sto sviluppando una libreria interna all'azienda (o come progetto secondario per me stesso) che verrà utilizzata con il suo codice sorgente completo. Quello che propongo è di mettere i grandi blocchi di commento nei file di implementazione (HPP, INL, CPP, ecc.) Per NON ingombrare l'interfaccia delle classi e delle funzioni dichiarate nell'intestazione.

Professionisti:

• Meno confusione nei file di intestazione, è possibile aggiungere solo la categorizzazione delle funzioni.
• I blocchi di commenti visualizzati in anteprima quando si utilizza Intellisense, ad esempio, non entrano in conflitto: questo è un difetto che ho osservato quando ho un blocco di commenti per una funzione nel file .H e ho la sua definizione inline nello stesso file .H ma incluso dal file .INL.

Contro:

• (L'ovvio) I blocchi di commento non sono nei file di intestazione dove si trovano le dichiarazioni.

Allora, cosa ne pensi e possibilmente suggerisci?

Metti la documentazione dove le persone la leggeranno e la scriveranno mentre usano e lavorano sul codice.

I commenti di classe vanno davanti alle classi, i commenti ai metodi davanti ai metodi.

Questo è il modo migliore per assicurarsi che le cose vengano mantenute. Mantiene anche i file di intestazione relativamente snelli ed evita il problema toccante delle persone che aggiornano i documenti del metodo che causano sporcizia delle intestazioni e attivano le ricostruzioni. In realtà ho saputo che le persone lo usano come scusa per scrivere la documentazione in seguito!

Mi piace sfruttare il fatto che i nomi possono essere documentati in più posti.

Nel file di intestazione, scrivo una breve descrizione del metodo e documento tutti i suoi parametri: è meno probabile che cambino rispetto all'implementazione del metodo stesso e, se lo fanno, il prototipo della funzione deve essere modificato in ogni caso .

Ho inserito la documentazione in formato lungo nei file di origine accanto all'implementazione effettiva, in modo che i dettagli possano essere modificati man mano che il metodo si evolve.

Per esempio:

mymodule.h

/// @brief This method adds two integers.
/// @param a First integer to add.
/// @param b Second integer to add.
/// @return The sum of both parameters.
int add(int a, int b);

mymodule.cpp

/// This method uses a little-known variant of integer addition known as
/// Sophocles' Scissors. It optimises the function's performance on many
/// platforms that we may or may not choose to target in the future.
/// @TODO make sure I implemented the algorithm correctly with some unit tests.
int add(int a, int b) {
  return b + a;
}

La presenza di commenti nell'intestazione significa che tutti gli utenti di una classe devono essere ricompilati se un commento viene modificato. Per progetti di grandi dimensioni, i programmatori saranno meno inclini ad aggiornare i commenti nelle intestazioni se rischiano di spendere i prossimi 20 minuti per ricostruire tutto.

E .. poiché si suppone che tu debba leggere il documento html e non sfogliare il codice per la documentazione, non è un grosso problema che i blocchi di commento siano più difficili da individuare nei file sorgente.

Intestazioni: è più facile leggere i commenti poiché c'è meno altro "rumore" quando si guardano i file.

Fonte: Quindi hai le funzioni effettive disponibili per la lettura mentre guardi i commenti.

Usiamo solo tutte le funzioni globali commentate nelle intestazioni e le funzioni locali commentate nel sorgente. Se vuoi puoi includere anche il comando copydoc per inserire la documentazione in più posti senza doverla riscrivere più volte (meglio per la manutenzione)

Tuttavia, è anche possibile copiare i risultati in una documentazione di file diversa con un semplice comando. Per esempio :-

Il mio file1.h

/**
 * \brief Short about function
 *
 * More about function
 */
WORD my_fync1(BYTE*);

MY file1.c

/** \copydoc my_func1 */
WORD my_fync1(BYTE* data){/*code*/}

Ora ottieni la stessa documentazione su entrambe le funzioni.

Questo ti dà meno rumore nei file di codice e allo stesso tempo ottieni la documentazione scritta in un punto presentata in diversi punti nell'output finale.

Di solito metto la documentazione per l'interfaccia (\ param, \ return) nel file .h e la documentazione per l'implementazione (\ details) nel file .c / .cpp / .m. Doxygen raggruppa tutto nella documentazione della funzione / metodo.

Ho messo tutto nel file di intestazione.

Documento tutto, ma estraggo solo generalmente l'interfaccia pubblica.

Sto usando QtCreator per la programmazione. Un trucco molto utile consiste nel fare Ctrl-clic su una funzione o un metodo per ottenere la dichiarazione nel file di intestazione.

Quando il metodo viene commentato nel file di intestazione, puoi trovare rapidamente le informazioni che stai cercando. Quindi per me, i commenti dovrebbero trovarsi nel file di intestazione!

In c ++ a volte l'implementazione può essere suddivisa tra moduli header e .cpp. Qui sembra più pulito mettere la documentazione nel file di intestazione poiché questo è l'unico posto in cui sono garantite tutte le funzioni ei metodi pubblici.