/** @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)

Powyższy kod deklaruje struktury q31_t i q25_t. Chciałbym je udokumentować za pomocą doksynu, ale cokolwiek próbowałem, struktury nie pojawiają się w dokumentacji. Nie są nawet wymienione. Initial Structor f32_t jest jedynym udokumentowanym.

Czy to może zostać naprawione?

2
Danijel 17 luty 2017, 17:37

2 odpowiedzi

Najlepsza odpowiedź

Podstawowy problem wydaje się uczestniczył w skład komentarzu dokumentacji w makro. Uważam, że jeśli umieściłem komentarz DOC z inwawansem makro , znajduje odzwierciedlenie w wygenerowanej dokumentacji; W przeciwnym razie nie jest. Oczywiście musisz skonfigurować doxygen, aby rozwinąć makra, które nie jest jego domyślnym zachowaniem.

Na przykład:

/** @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 */

(Przeprowadziłem również średnik końcowy z makra, ale z komentarzem DOC również przeniesiony, jest to tylko kwestia stylu.)

To ma sens, ponieważ jedna z rzeczy preprocesor jest konwertowany komentarze do białego znaku. Nie jest oczywiste, że doxygen musi to zrobić w sposób, który powoduje, że ignoruje komentarze doc w makrach, ale nie jest to nieuzasadnione.

1
John Bollinger 17 luty 2017, 16:27

Jest trochę późno, ale odpowiedź John jest nieco niekompletna. Druga rzecz, którą możesz tutaj zrobić, jest ustawiony MACRO_EXPANSION=YES. Ma to negatywny efekt uboczny rozszerzania wszystkie makra, więc następnego do zrobienia jest EXPAND_ONLY_PREDEF=YES. To ogranicza tylko makra zdefiniowane w sekcji PREDEFINED lub wymienione w sekcji EXPAND_AS_DEFINED. Więc jeśli dodasz swoje makro do tej listy, byłoby to jedyne rozszerzone.

1
gabe appleton 16 październik 2019, 00:26