Dokumentieren Makros Doxygen

Question

/** @brief This is my initial struct. */ 
typedef struct 
{ 
    f32 v; /**< Value. */ 
    int32 s; /**< Scale. */ 
} f32_t; 

#define DECLARE_TYPE(N) \ 
     typedef f32_t q##N##_t; /**< This is my Q struct. */ 

DECLARE_TYPE(31) 
DECLARE_TYPE(25) 

Die obige Code deklariert eine q31_t und q25_t structs. Ich möchte sie mit Doxygen dokumentieren, aber was auch immer ich versuchte, die Strukturen erscheinen nicht in der Dokumentation. Sie werden nicht einmal erwähnt. Die erste Struktur f32_t ist die einzige, die dokumentiert ist.

Kann dies behoben werden?

Answer 1

Das Hauptproblem scheint darin zu liegen, den Dokumentationskommentar in das Makro zu schreiben. Ich finde, dass, wenn ich den Doc-Kommentar mit dem Makro Aufruf setzen, dann wird es in der generierten Dokumentation widerspiegelt; Sonst ist es nicht. Natürlich müssen Sie Doxygen konfigurieren, um Makros zu erweitern, was nicht das Standardverhalten ist.

Zum Beispiel:

/** @brief This is my initial struct. */ 
typedef struct 
{ 
    ae_f32 v; /**< Value. */ 
    ae_int32 s; /**< Scale. */ 
} ae_f32_t; 

#define DECLARE_TYPE(N) \ 
     typedef ae_f32_t ae_q##N##_t 

DECLARE_TYPE(31); /**< @brief This is my Q31 struct */ 
DECLARE_TYPE(25); /**< @brief This is my Q25 struct */ 

(Ich habe auch das abschließende Semikolon aus dem Makro bewegte, aber mit dem Doc-Kommentar auch bewegt wird, dann ist dies eine Frage des Stils nur.)

Diese macht einen Sinn, da der Präprozessor die Kommentare in Whitespace konvertiert. Es ist nicht offensichtlich, dass Doxygen dies so tun muss, dass Doc-Kommentare in Makros ignoriert werden, aber es ist nicht unvernünftig, dies zu tun.