In .h-Dateien sollten die Deklarationen von Dingen stehen, die
"öffentlich" (implizit oder explizit extern) sind. Dort und nur dort
werden die Deklarationen auch vollständig mit Doxygen-Kommentaren
dokumentiert.
Die Idee dahinter ist, die öffentliche Schnittstelle eines Moduls in der
Datei zu dokumentieren, die für andere Module die öffentliche
Schnittstelle deklariert und von anderen Modulen per #include geladen
wird.
In .c-Dateien stehen die Definitionen von öffentlichen und die
Definitionen und Deklarationen von privaten (static) Dingen. Dort wird
nur das dokumentiert, was noch nicht in den .h-Dateien dokumentiert ist,
d.h. die privaten (static) Funktionen, Variablen, Konstanten, etc., die
außerhalb der Datei nicht sichtbar sind und keine öffentliche
Schnittstelle eines Moduls darstellen. Als nur interne
Entwicklerdokumentation.
@brief ist nicht für eine separate Kurzdokumentation gedacht, sondern
für eine einleitende, prägnante Zusammenfassung was eine
Funktion/Variable/etc. denn macht, gefolgt von einer detaillierten
Beschreibung. @brief gehört zu detaillierten Beschreibung. Die
Kurzbeschreibungen tauchen zum Beispiel in Übersichtstabellen auf.
JavaDoc-Benutzer kennen das in der Form, dass bei JavaDoc der erste Satz
in einer Beschreibung automatisch als Kurzbeschreibung verwendet wird
(Doxygen kann ebenfalls so konfiguriert werden, dass es das automatisch
ohne @brief macht).
