Czy zmienne komentujące powiązane z Doxygen zawierają jakiekolwiek kary?

Question

widzę większość docs Doxygen do komentowania C++ funkcje szukają czegoś podobnego do

/// a description of the function or method followed with comments, like so 
/// @return true=success, false=error 
/// @param[in] bar blah blah 
/// @param[out] baz blah blah 
/// @param[out] quux blah blah 
/// @param[out] quuux blah blah 
/// @param[out] quuuux blah blah 
static bool foo_one(int *bar, int *baz, int *quux, int *quuux, int *quuuux); 

lub równowartość xml (w przybliżeniu)

/// a description of the function or method, followed by 
/// <returns>true=success, false=error</returns> 
/// <param name=bar>blah blah</param> 
/// <param name=baz>blah blah</param> 
/// <param name=quux>blah blah</param> 
/// <param name=quuux>blah blah</param> 
/// <param name=quuuux>blah blah</param> 
static bool foo_two(int *bar, int *baz, int *quux, int *quuux, int *quuuux); 

ale byłem głównie komentując moje parametry inline, podobnie jak

/// a description of the function or method, followed by 
/// @return true=success, false=error 
static bool foo_three(
    int *bar,    ///< [in] blah blah 
    int *baz,    ///< [out] blah blah 
    int *quux,    ///< [out] blah blah 
    int *quuux,    ///< [out] blah blah 
    int *quuuux    ///< [out] blah blah 
); 

Wszystkie trzy dają identyczny wynik w pliku html (z wyjątkiem środkowego, który nie określa w /na zewnątrz).

Moje pytanie: Czy są dostępne funkcje Doxygen, Visual Studio lub innych środowisk, których nie będę w stanie wykorzystać z moim podejściem inline? Rozumiem, że istnieją osobiste preferencje podczas pisania i czytania komentarzy w samym kodzie i wolałbym nie debatować nad nimi. Interesuje mnie tylko wiedzieć, czy istnieją Doxygen lub inne funkcje środowiskowe lub formatowanie, których będę brakować.

Answer 1

Tak.

Sam Doxygen będzie działał dobrze z komentarzami wstawianymi.

jednak również wziąć pod uwagę wpływ na historię nagranego przez system kontroli kodu źródłowego (np git i git blame)

Z inline komentarze, ostatni człowiek, który zmienił linię jest ktokolwiek dodane lub zmienione w dokumentacji, co sprawia, że ​​trudniej jest znaleźć, kiedy/dlaczego sam kod został zmieniony.

Po komentarzach w oddzielnych wierszach, szczególnie jeśli dokumentacja jest dodawana po kodzie, sprawdzanie historii w celu znalezienia zmian kodu jest łatwiejsze.