Looking for doxygen Answers? Try Ask4KnowledgeBase
Looking for doxygen Keywords? Try Ask4Keywords

doxygenRozpoczęcie pracy z doxygen


Uwagi

Ta sekcja zawiera przegląd tego, czym jest doxygen i dlaczego deweloper może chcieć go użyć.

Powinien również wymieniać wszelkie duże tematy w doxygen i link do powiązanych tematów. Ponieważ Dokumentacja doxygen jest nowa, konieczne może być utworzenie początkowych wersji tych powiązanych tematów.

Komentowanie twojego kodu

Istnieje kilka sposobów oznaczenia bloku komentarza jako szczegółowego opisu, dzięki czemu ten blok komentarza jest analizowany przez Doxygen i dodawany jako opis następującego elementu kodu do dokumentacji. Pierwszym i najczęściej stosowanym są komentarze w stylu C z dodatkową gwiazdką w sekwencji początkowej komentarza, np .:

/**
 * … text …
 */
int dummy_var;
 

Kolejną alternatywą jest użycie stylu Qt i dodanie wykrzyknika (!) Po sekwencji otwierającej bloku komentarza w stylu C:

/*!
 * … text …
 */
void foo(void);
 

Trzecią alternatywą jest użycie bloku co najmniej dwóch linii komentarza C ++, przy czym każda linia zaczyna się od dodatkowego ukośnika lub wykrzyknika:

/// 
/// ... text ... 
///
 

lub

//! 
//! ... text ... 
//!
 

Niektóre osoby lubią zwiększać widoczność bloków komentarzy w dokumentacji. W tym celu możesz użyć:

 /********************************************//** 
  * ... text 
  ***********************************************/
 

Zwróć uwagę na 2 ukośniki, aby zakończyć normalny blok komentarza i rozpocząć specjalny blok komentarza.

/////////////////////////////////////////////////
/// ... text ...
/////////////////////////////////////////////////
 

Aby ustrukturyzować i zapisać wygenerowaną dokumentację, Doxygen udostępnia dużą liczbę (> 170) specjalnych poleceń. Wszystkie polecenia w dokumentacji zaczynają się od ukośnika odwrotnego () lub znaku at (@).

Na przykład

/**
 * \brief    A brief description in one short sentence.
 */
 

jest równa

/**
 * @brief    A brief description in one short sentence.
 */
 

Dla krótkiego opisu istnieje również kilka możliwości:

Można użyć polecenia \brief z jednym z powyższych bloków komentarzy. To polecenie kończy się na końcu akapitu, więc szczegółowy opis następuje po pustej linii.

/** \brief Brief description. 
 * Brief description continued. 
 * 
 * Detailed description starts here. 
 */ 
 

Jeśli JAVADOC_AUTOBRIEF jest ustawiony na YES w pliku konfiguracyjnym, wówczas użycie bloków komentarzy w stylu JavaDoc automatycznie rozpocznie krótki opis, który kończy się na pierwszej kropce, po której następuje spacja lub nowy wiersz.

/// Brief description which ends at this dot. Details follow 
/// here. 
 

I na koniec tutaj przykład pełnej dokumentacji funkcji z doxygen:

/**
 * \brief   The function bar. 
 *
 * \details This function does something which is doing nothing. So this text
 *          is totally senseless and you really do not need to read this,
 *          because this text is basically saying nothing.
 *
 * \note    This text shall only show you, how such a \"note\" section
 *          is looking. There is nothing which really needs your notice,
 *          so you do not really need to read this section.
 *
 * \param[in]     a    Description of parameter a.
 * \param[out]    b    Description of the parameter b.
 * \param[in,out] c    Description of the parameter c.
 *
 * \return        The error return code of the function.
 *
 * \retval        ERR_SUCCESS    The function is successfully executed
 * \retval        ERR_FAILURE    An error occurred
 */

errcode_t bar(int a, int b, int c)
{    
    /** More detailed description inside the code */
}
 

źródło i więcej informacji na stronie głównej Doxygen

Instalacja lub konfiguracja

Szczegółowe instrukcje dotyczące konfiguracji lub instalacji doxygen.