Gdzie umieścić bloki komentarzy doxygen dla wewnętrznej biblioteki - w plikach H czy CPP? [Zamknięte]

Zdrowy rozsądek mówi, że bloki komentarzy Doxygen muszą być umieszczane w plikach nagłówkowych, w których znajdują się klasy, struktury, wyliczenia, funkcje, deklaracje. Zgadzam się, że jest to rozsądny argument dla bibliotek, które mają być dystrybuowane bez źródła (tylko nagłówki i biblioteki z kodem wynikowym).

ALE ... Myślałem o dokładnie odwrotnym podejściu, kiedy tworzę wewnętrzną bibliotekę firmy (lub jako projekt poboczny dla siebie), która będzie używana z pełnym kodem źródłowym. Proponuję umieścić duże bloki komentarzy w plikach implementacji (HPP, INL, CPP, itp.), Aby NIE zaśmiecać interfejsu klas i funkcji zadeklarowanych w nagłówku.

Plusy:

• Mniej bałaganu w plikach nagłówkowych, można dodać tylko kategoryzację funkcji.
• Bloki komentarzy, które są przeglądane, gdy używany jest na przykład Intellisense, nie kolidują - jest to wada, którą zauważyłem, gdy mam blok komentarza dla funkcji w pliku .H i mam jej definicję w tym samym pliku .H ale zawarte z pliku .INL.

Cons:

• (Oczywisty) Bloki komentarzy nie znajdują się w plikach nagłówkowych, w których znajdują się deklaracje.

Więc co myślisz i prawdopodobnie sugerujesz?

Umieść dokumentację w miejscu, w którym ludzie będą ją czytać i pisać podczas używania i pracy nad kodem.

Komentarze klas znajdują się przed klasami, komentarze metod przed metodami.

To najlepszy sposób, aby upewnić się, że wszystko jest w porządku. Utrzymuje również względnie oszczędne pliki nagłówkowe i pozwala uniknąć rażącego problemu ludzi aktualizujących dokumenty metod, które powodują zabrudzenie nagłówków i wyzwalanie przebudowy. Właściwie wiedziałem, że ludzie używają tego jako pretekstu do późniejszego pisania dokumentacji !

Lubię wykorzystywać fakt, że nazwiska mogą być dokumentowane w wielu miejscach.

W pliku nagłówkowym piszę krótki opis metody i dokumentuję wszystkie jej parametry - są one mniej skłonne do zmiany niż sama implementacja metody, a jeśli tak, to prototyp funkcji i tak trzeba zmienić .

Dokumentację w długim formacie umieściłem w plikach źródłowych obok samej implementacji, więc szczegóły można zmieniać w miarę rozwoju metody.

Na przykład:

mymodule.h

/// @brief This method adds two integers.
/// @param a First integer to add.
/// @param b Second integer to add.
/// @return The sum of both parameters.
int add(int a, int b);

mymodule.cpp

/// This method uses a little-known variant of integer addition known as
/// Sophocles' Scissors. It optimises the function's performance on many
/// platforms that we may or may not choose to target in the future.
/// @TODO make sure I implemented the algorithm correctly with some unit tests.
int add(int a, int b) {
  return b + a;
}

Posiadanie komentarzy w nagłówku oznacza, że ​​wszyscy użytkownicy klasy muszą zostać ponownie skompilowani, jeśli komentarz zostanie zmieniony. W przypadku dużych projektów programiści będą mniej skłonni do aktualizowania komentarzy w nagłówkach, jeśli zaryzykują spędzenie następnych 20 minut na odbudowie wszystkiego.

I ... ponieważ powinieneś czytać dokument HTML i nie przeglądać kodu w poszukiwaniu dokumentacji, nie jest dużym problemem, że bloki komentarzy są trudniejsze do zlokalizowania w plikach źródłowych.

Nagłówki: łatwiejsze do odczytania komentarze, ponieważ podczas przeglądania plików jest mniej innych „szumów”.

Źródło: Następnie masz rzeczywiste funkcje dostępne do czytania podczas przeglądania komentarzy.

Po prostu używamy wszystkich funkcji globalnych komentowanych w nagłówkach i funkcji lokalnych komentowanych w źródle. Jeśli chcesz, możesz również dołączyć polecenie copydoc, aby wstawić dokumentację w wielu miejscach bez konieczności jej wielokrotnego pisania (lepsze do konserwacji)

Możesz jednak również skopiować wyniki do innej dokumentacji pliku za pomocą prostego polecenia. Np .: -

Mój plik1.h

/**
 * \brief Short about function
 *
 * More about function
 */
WORD my_fync1(BYTE*);

MÓJ plik1.c

/** \copydoc my_func1 */
WORD my_fync1(BYTE* data){/*code*/}

Teraz masz tę samą dokumentację dla obu funkcji.

Daje to mniej szumu w plikach kodu, a jednocześnie dokumentację zapisaną w jednym miejscu, prezentowaną w kilku miejscach na końcowym wyjściu.

Zazwyczaj dokumentację interfejsu (\ param, \ return) umieszczam w pliku .h, a dokumentację dotyczącą implementacji (\ details) w pliku .c / .cpp / .m. Doxygen grupuje wszystko w dokumentacji funkcji / metody.

Umieściłem wszystko w pliku nagłówkowym.

Dokumentuję wszystko, ale ogólnie wyodrębniam tylko interfejs publiczny.

Do programowania używam QtCreator. Bardzo przydatna sztuczka polega na kliknięciu z klawiszem Ctrl funkcji lub metody w celu uzyskania deklaracji w pliku nagłówkowym.

Gdy metoda jest opatrzona komentarzem w pliku nagłówkowym, możesz szybko znaleźć informacje, których szukasz. Więc jak dla mnie, komentarze powinny znajdować się w pliku nagłówkowym!

W C ++ czasami implementację można podzielić na moduły nagłówkowe i .cpp. Tutaj wydaje się czystsze, aby umieścić dokumentację w pliku nagłówkowym, ponieważ jest to jedyne miejsce, w którym wszystkie publiczne funkcje i metody są gwarantowane.