Czy jest jakaś sztuczka, aby zredukować ilość zbędnych komentarzy wymaganych do pełnego pokrycia Doxygen?

Question

W ramach dokumentowania mojej bazy kodu C++ staram się uzyskać pełny zasięg Doxygen - to znaczy, że chcę, aby wszystkie moje (setki) plików nagłówkowych miały dobrze sformułowane komentarze Doxygen dla wszystkich ich publicznych API, tak, że mogę uruchomić Doxygen na bazie kodu i nie widzę żadnych ostrzeżeń "ostrzeżenie: bla nie jest udokumentowane".

Ogólnie rzecz biorąc jest to tylko kwestia przechodzenia i dokumentowania rzeczy, ale zauważyłem, że wciąż powtarzam ten sam tekst dla każdej klasy. Na przykład, mam wiele wystąpień w zasadzie tak:

/** The Foo class represents blah blah blah */ 
class Foo 
{ 
public: 
    /** Default constructor */ 
    Foo(); 

    /** Copy constructor 
     * @param rhs the object to make this object a copy of. 
     */ 
    Foo(const Foo & rhs); 

    /** Destructor */ 
    ~Foo(); 

    /** Equality operator. 
     * @param rhs the object to compare against. 
     * @returns true iff this object and (rhs) are equal. 
     */ 
    bool operator == (const Foo & rhs) const; 

    /** Inequality operator. 
     * @param rhs the object to compare against. 
     * @returns true iff this object and (rhs) are not equal. 
     */ 
    bool operator != (const Foo & rhs) const; 

    /** Assignment operator 
     * @param rhs the object we should copy our state from 
     * @returns a reference to *this 
     */ 
    Foo & operator = (const Foo & rhs); 

[...] 
} 

Te komentarze są (zazwyczaj) bardziej lub mniej dokładnie takie same dla każdej klasy, ponieważ te funkcje/operatorzy niemal zawsze działają dokładnie w ten sam sposób dla każdego klasa. Rzeczywiście, posiadanie operatorów lub konstruktorów kopiujących, którzy zachowywaliby się w jakiś inny sposób, byłoby wątpliwym wzorcem projektowym, ponieważ programiści C++ zasadniczo oczekują, że operatorzy pracują w ten sam sposób dla każdej klasy.

Moje pytanie brzmi, czy jest jakaś sztuczka, dzięki której mogę powiedzieć Doxygenowi, aby automatycznie generował rozsądną dokumentację dla tych rzeczy (np. Za pośrednictwem jakiegoś szablonu lub makra) bez konieczności ręcznego wprowadzania tego tekstu w kółko? Znacznie ograniczyłoby to ilość tekstu, który muszę wprowadzić i utrzymać, a także usunąłoby bałagan z moich plików nagłówkowych, pozwalając mi na usunięcie komentarzy odmiany "no duh", aby czytelnik mógł łatwiej znaleźć komentarze które oferują prawdziwy wgląd.

Answer 1

Istnieje kilka komend dla dokumentacji Kopiowanie:

\copydoc \copybrief \copydetails

Doxygen pomoc sugeruje następującą składnię:

/*! @copydoc MyClass::myfunction() 
* More documentation. 
*/ 

To pozwala kopiować dokumentację z jednej klasy do drugiej . Czasami tworzę tylko dokumentację klasy, która nie jest skompilowana jako standardowe miejsce do rysowania dokumentacji od reszty projektu.