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

Lubię korzystać z faktu, że nazwy mogą być udokumentowane w wielu miejscach.

W pliku nagłówkowym piszę Krótki opis metody i dokumentuję wszystkie jej parametry - są one mniej prawdopodobne, aby się zmieniły niż implementacja samej metody, a jeśli tak, to prototyp funkcji musi zostać zmieniony w każdym przypadku.

Umieszczam długoformatową dokumentację w plikach źródłowych obok rzeczywistej implementacji, więc szczegóły można zmienić jako metodę ewoluuje.

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ć przekompilowani, 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 przebudowie wszystkiego.

I.. ponieważ powinieneś czytać dokument html, a nie przeglądać kod w celu uzyskania dokumentacji, nie jest dużym problemem, że bloki komentarzy są trudniejsze do zlokalizowania w plikach źródłowych.

nagłówki: Łatwiej czytać komentarze, ponieważ jest mniej innych "szumów" podczas przeglądania plików.

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

Używamy tylko wszystkich globalnych funkcji komentowanych w nagłówkach i lokalnych funkcji komentowanych w source. Jeśli chcesz, możesz również dołączyć polecenie copydoc, aby wstawić dokumentację w wielu miejscach bez konieczności jej pisania kilka razy ( lepiej dla maintenance)

Możesz jednak również uzyskać wyniki skopiowane 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 dostajesz tę samą dokumentację dla obu funkcji.

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

Zazwyczaj umieszczam w nim dokumentację interfejsu (\param, \ return).H plik i dokumentacja do wdrożenia (\details) w .c/.cpp/plik M. Doxygen grupuje wszystko w dokumentacji funkcji/metody.

Umieszczam wszystko w pliku nagłówkowym.

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

Używam QtCreator do programowania. Bardzo przydatna sztuczka polega na kliknięciu Ctrl na funkcji lub metodzie, aby uzyskać deklarację w pliku nagłówkowym.

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

W c++ czasami implementację można podzielić między nagłówek i .Moduły cpp. Tutaj wydaje się czystsze umieszczenie dokumentacji w pliku nagłówkowym, ponieważ jest to jedyne miejsce, w którym gwarantowane są wszystkie publiczne funkcje i metody.