Dokumentowanie zmienne z Doxygen w C

Question

Kod:

#include <stdio.h> 

/* 
* \var int iOne 
* \brief Integer 1 
*/ 
/* 
* \var int iTwo 
* \brief Integer 2 
*/ 
/* 
* \var int iThree 
* \brief Integer 3 
*/ 

/** 
* \brief Imitates a sheep. 
*/ 
void sheep(); 

/** 
* \brief Main function for test code 
*/ 
int main() { 
    int iOne, iTwo, iThree; 
    iOne = 1; 
    iTwo = 2; 
    iThree = 3; 
    printf("%d %d %d", iOne, iTwo, iThree); 

    return 0; 
} 

void sheep() { 
    printf("Meeeh"); 
} 

ten nie generuje opisy iOne, iTwo i iThree mimo że było moim zamiarem. Jak to naprawić?

Answer 1

Musisz otworzyć swoje komentarze jako komentarze Doxygen z /**.

mogą być jaśniejsze, aby to zrobić, choć:

int main() { 
    /** \brief Integer 1 */ 
    int iOne; 
    /** \brief Integer 2 */ 
    int iTwo; 
    /** \brief Integer 3 */ 
    int iThree; 
    /** ... and so on ... */ 
} 

W ten sposób można zmienić nazwę zmiennej bez zerwania dokumentację i to także łatwiejszy od innych programistów, którzy potrzebują odczytać kodu źródłowego, ponieważ opis zmiennej znajduje się obok niej, a nie gdzie indziej w pliku.

Answer 2

DOxygen został stworzony do dokumentowania klas i nagłówków funkcji lub, innymi słowy, interfejsu interfejsu. Pomyśl o dokumentacji jako o czymś, co studiują inni programiści, aby prawidłowo korzystać z twoich zajęć i funkcji. Nie należy używać DOxygen do dokumentowania implementacji. Zamiast tego udokumentuj zmienne lokalne w źródle za pomocą // lub /* */.

Istnieje kilka sposobów na komentarze w DOxygen, niektóre przykłady (dla zmiennych członkowskich) można znaleźć w instrukcji here. Skopiowałem je poniżej.

int var; /*!< Detailed description after the member */ 

int var; /**< Detailed description after the member */ 

int var; //!< Detailed description after the member 
     //!< 

int var; ///< Detailed description after the member 
     ///< 

int var; //!< Brief description after the member 

int var; ///< Brief description after the member