Kommentieren Variablen in Doxygen mit irgendwelchen Strafen?

Question

Ich sehe die meisten Doxygen Dokumentation für Kommentierung C++ Funktionen so etwas wie

/// 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); 

oder der XML-Äquivalent (grob) suchen

/// 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); 

aber ich habe meine Parameter wurden meist kommentiert inline, wie so

/// 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 
); 

Alle drei davon gibt identischen Ausgang in der hTML-Datei (mit Ausnahme des mittleren, die nicht in spezifiziert /aus).

Meine Frage: Gibt es Funktionen von Doxygen, Visual Studio oder einer anderen Umgebung, die ich mit meinem Inline-Ansatz nicht nutzen kann? Ich verstehe, dass es beim Schreiben und Lesen der Kommentare im Code selbst persönliche Präferenzen gibt, und möchte diese nicht diskutieren. Ich bin nur daran interessiert zu wissen, ob es Doxygen oder andere Umgebungsmerkmale oder Formatierungen gibt, die ich verpasse.

Answer 1

Ja.

Doxygen selbst wird gut mit Inline-Kommentaren funktionieren.

jedoch auch die Wirkung auf der Geschichte von dem Source Code Control System (zum Beispiel git und git blame) aufgezeichnet betrachten

Mit Inline-Kommentaren, die letzte Person, die die Linie gewechselt ist, wer hinzugefügt oder Dokumentation geändert, Das macht es schwieriger zu finden, wann/warum der Code selbst geändert wurde.

Mit Kommentaren zu separaten Zeilen, insbesondere wenn die Dokumentation nach dem Code hinzugefügt wird, ist es einfacher, den Verlauf zu überprüfen, um Codeänderungen zu finden.