Come posso mantenere doxygen dalla documentazione di #defines in un file C?

Question

Ho i valori di #define nelle intestazioni che desidero che Doxygen desideri documentare, ma ne ho altri in C file che considero come costanti statiche e non voglio che Doxygen li documenti. Qualcosa di semplice e stupido come

#define NUMBER_OF(a) (sizeof((a))/sizeof((a)[0])) 
#define MSTR(e) #e 

Come posso tenere Doxygen da mettere quelle #define s nella documentazione che crea? Ho provato a contrassegnarlo con @internal ma questo non sembra essere d'aiuto.

Una domanda un po 'legati a Doxygen e #define, come posso ottenere:

#define SOME_CONSTANT 1234 /**< An explanation */ 

di mettere "SOME_CONSTANT" e "Una spiegazione", ma non "1234" in uscita?

Answer 1

È possibile escludere qualsiasi parte del codice dall'analisi di Doxygen con i tag \cond...\endcond.

Modifica: Alcune domande correlati:

• How can Doxygen exclude a C++ class?
• Exclude some classes from doxygen documentation

Answer 2

Sarà senza dubbio sembrano ancora rumorosa e innaturale, ma per affrontare la vostra altra domanda, provare:

/** An explanation */ 
#define SOME_CONSTANT /** @cond */ 1234 /** @endcond */ 

Answer 3

Puoi impostare MAX_INITIALIZER_LINES = 0 nel tuo doxyfile per nascondere i valori delle tue definizioni.

Answer 4

Non è necessario utilizzare i comandi \cond e \endcond. È possibile nascondere l'inizializzatore semplicemente usando il comando \hideinitializer:

#define SOME_CONSTANT 1234 /**< An explanation @hideinitializer */ 

Per quanto riguarda la prima domanda, è possibile impostare HIDE_UNDOC_MEMBERS = YES e solo le macro con un blocco di documentazione Doxygen verrà mostrato in uscita.

Answer 5

Si desidera solo documentare quanto dichiarato nei file .h. Presumo che dichiari tutte le funzioni e le variabili statiche come static nei tuoi file .c. Tutti i rimanenti sono dichiarati anche nei file corrispondenti . Questi sono i tuoi membri "pubblici".

Quello che mi piace fare in questo caso, e credo Doxygen era più progettato per essere utilizzato in questo modo è:

• nel vostro Doxyfile, impostare EXTRACT_ALL = NO e aggiungere la directory in cui i file .h sono INPUT
• aggiungi /** \file */ a tutti i tuoi file .h (ma non i tuoi file .c).

Questo indicherà solo ciò che è contenuto nei file .h.È comunque possibile aggiungere la directory contenente i file .c a INPUT a vostra Doxyfile, ed essi saranno sottoposti a scansione per la documentazione aggiuntiva per i soci "pubblici" ...

Answer 6

Ho risolto questo problema spostando la mia documentazione dal file .c al file .h. Quindi esegui doxygen solo sul file .h.

Quindi gli elementi che voglio documentare (gli elementi "pubblici") sono intrinsecamente ciò che rileva l'ossigeno.

Poiché in precedenza sono stato attento a inserire elementi "pubblici" nel file .h e nel file .c nel file .c, questo funziona molto bene.

Questa tecnica mi è venuta in mente quando ho notato che doxygen stava inserendo gli include. Mi ha colpito il fatto che se dovessi spostare anche il sottoinsieme di include che il modulo chiamante avrebbe bisogno di usare il mio modulo, allora quell'elenco sarebbe anche documentato.

Questa tecnica ha un ulteriore vantaggio: posso inserire la documentazione in una finestra di terminale e l'origine in una finestra di terminale diversa durante l'aggiornamento della documentazione.