La definizione del preprocessore si definisce in Doxygen

Question

È possibile documentare le definizioni del preprocessore in Doxygen? Mi aspettavo di essere in grado di farlo proprio come una variabile o una funzione, tuttavia l'output di Doxygen sembra aver "perso" la documentazione per la definizione e non contiene nemmeno la definizione stessa.

Ho provato il seguente

/**My Preprocessor Macro.*/ 
#define TEST_DEFINE(x) (x*x) 

e

/**@def TEST_DEFINE 

    My Preprocessor Macro. 
*/ 
#define TEST_DEFINE(x) (x*x) 

Ho anche provato mettendoli all'interno di un gruppo (defgroup provato, AggiungiAlGruppo e ingroup) piuttosto che al "nell'ambito di file", tuttavia, che non ha avuto alcun effetto (sebbene altri elementi del gruppo siano stati documentati come previsto).

Ho esaminato le varie opzioni di Doxygen, ma non sono riuscito a vedere nulla che potesse abilitare (o impedire) la documentazione delle definizioni.

Answer 1

Sì, è possibile. Il Doxygen documentation dice:

per documentare gli oggetti globali (funzioni, typedef, enum, macro, ecc), è necessario documentare il file in cui sono definiti. In altre parole, ci deve essere almeno un

/** @file */

linea

/*! \file */

o un in questo file.

È possibile utilizzare @defgroup, @addtogroup, e @ingroup di mettere elementi correlati nello stesso modulo, anche se appaiono in file separati (vedere la documentazione here per i dettagli). Ecco un esempio minimo che funziona per me (usando Doxygen 1.6.3):

Doxyfile:

# Empty file. 

Test.h:

/** @file */ 

/**My Preprocessor Macro.*/ 
#define TEST_DEFINE(x) (x*x) 

/** 
* @defgroup TEST_GROUP Test Group 
* 
* @{ 
*/ 

/** Test AAA documentation. */ 
#define TEST_AAA (1) 
/** Test BBB documentation. */ 
#define TEST_BBB (2) 
/** Test CCC documentation. */ 
#define TEST_CCC (3) 
/** @} */ 

foo.h:

/** @file */ 

/** 
* @addtogroup TEST_GROUP 
* 
* @{ 
*/ 

/** @brief My Class. */  
class Foo { 
    public: 
     void method(); 
}; 

/** @} */ 

Bar.h:

/** @file */ 

/** 
* @ingroup TEST_GROUP 
* My Function. 
*/ 
void Bar(); 

In questo caso, la documentazione TEST_DEFINE appare nella test.h voce sotto la scheda file nella output HTML, e le definizioni TEST_AAA ecc appaiono sotto Gruppo di prove nelle moduli scheda con classe Foo e la funzione Bar.

Una cosa da notare è che se si mette il nome del file dopo il @file di comando, per esempio:

/** @file Test.h */ 

allora questo deve corrispondere al nome effettivo del file. In caso contrario, la documentazione per gli elementi nel file non verrà generata.

Una soluzione alternativa, se non si desidera aggiungere comandi @file, è impostare EXTRACT_ALL = YES nel Doxyfile.

Spero che questo aiuti!

Answer 2

Provare a impostare l'opzione EXTRACT_ALL, l'ho impostato nel mio progetto e genera la documentazione per #defines. Ci potrebbe essere un modo più elegante di farlo senza usare EXTRACT_ALL in modo da essere sicuri di controllare la documentazione

http://www.doxygen.nl/config.html#cfg_extract_all

Answer 3

nei miei file "C", io uso un formato di commento e la linea # define in questo modo:

/** @brief Number of milli-seconds to wait*/ 
#define kTimeoutMSec (2) 

miei documenti HTML non finiscono contenente la documentazione specificata. (Ho @file nella parte superiore del file e EXTRACT_ALL = YES)

Answer 4

In aggiunta alle risposte precedenti, è anche necessario avere ENABLE_PREPROCESSING=YES sul Doxyfile.