Konsistente Kommentare in *.h und *.c Dateien

[Stephan M. (multimeter90)]

Hallo Leute,

ich habe für jedes SW-Modul ein h und ein c file. Die Kommentare für 
doxygen stehen alle im h-file. Ich hätte aber gern die Kommentare auch 
im c-file, zum Anschauen wärend ich die Funktion implementiere. Die 
Kommentare dürfen aber von doxygen nicht doppelt eingelesen werden und 
sollen immer konsistent sein, ohne manuelles copy&paste.
Kennt jemand ein Werkzeug dafür, welches nur die Kommentare abgleicht?

Für doxygen zum Verhindern des doppelten Einlesens habe ich hier
http://stackoverflow.com/questions/21264174/how-do-i-make-doxygen-ignore-function-like-macros-when-building-the-documentatio
die Lösung mit:

[...]
#ifndef DOXYGEN_SHOULD_SKIP_THIS

 /* code that must be skipped by Doxygen */

#endif /* DOXYGEN_SHOULD_SKIP_THIS */

around the blocks that should be hidden and put:

  PREDEFINED = DOXYGEN_SHOULD_SKIP_THIS

in the config file [...]

Ich hoffe ihr versteht das Problem?

[Pit (Gast)]

Wüsste auf anhieb nichts aber warum schreibt man Kommentare ins Header? 
Welche Vorteile siehst du darin? Schreib sie direkt über die Funktion, 
dann ist der Kommentar dort wo er auch hingehört.

[Dr. Sommer (Gast)]

Pit schrieb:
> Wüsste auf anhieb nichts aber warum schreibt man Kommentare ins
> Header?
Damit man, wenn man die Funktion "von außen" nutzt, den Kommentar sieht. 
Header bilden schließlich das Interface zu anderen Modulen, und nur das 
hat diese anderen Module zu interessieren! Die .c Datei kann genauso gut 
nur als binary (.o, .a, .so) vorliegen, da kann man bei Nutzung gar 
nichts drin lesen.

Wenn man einen großen Bildschirm hat kann man die .h und die .c Datei 
nebeneinander öffnen und kann dann die .h lesen während man die .c 
schreibt...

[Rolf Magnus (Gast)]

Pit schrieb:
> Wüsste auf anhieb nichts aber warum schreibt man Kommentare ins Header?
> Welche Vorteile siehst du darin? Schreib sie direkt über die Funktion,
> dann ist der Kommentar dort wo er auch hingehört.

Das ist eigentlich gerade das, wo er nicht hingehört. Der Kommentar 
gehört ins Interface, das man beim Aufruf der Funktion nutzt, also in 
den Header.

[Ast E. (vis)]

Rolf Magnus schrieb:
> Pit schrieb:
>> Wüsste auf anhieb nichts aber warum schreibt man Kommentare ins Header?
>> Welche Vorteile siehst du darin? Schreib sie direkt über die Funktion,
>> dann ist der Kommentar dort wo er auch hingehört.
>
> Das ist eigentlich gerade das, wo er nicht hingehört. Der Kommentar
> gehört ins Interface, das man beim Aufruf der Funktion nutzt, also in
> den Header.

richtig.

aber wozu im c File? Nur damit alle Parameter gesehen werden etc.? Dann 
entweder den selben Text kopieren oder eben im h-File nachschauen. Aber 
dafür extra aufwand betreiben? Damit während man beim coden ist der 
Überblick nicht verloren geht..?

[Stephan M. (multimeter90)]

Ja, die Kommentare im h-file dienen als Dokumentation für die anderen, 
welche das Modul benutzen (wollen).
Im c-file macht sich das aber auch sehr hilfreich, wenn man erstmal 
definiert, was die funktion machen soll (zB welches Timing, 
Berechnungsvorschrift als Formel etc) und danach programmieren kann.

Die Idee mit dem manuell Text kopieren gefällt mir nicht so gut, da 
irgendwann definitiv beide Kommentare inkonsistent sind.

Eine Idee wäre noch, die Kommentare in das c-file schreiben und zur 
Dokumentation des Interfaces (*.h) einfach die von doxygen erzeugten 
daten dazugeben.

[PittyJ (Gast)]

Ich packe die Kommentare in C-File.
Und die Dokumentation liefert doxygen ja später. Da schaut man doch eh 
nicht mehr ins H-File, sondern browst in den HTML-Seiten, die Doxygen 
erzeugt.

[Stephan M. (multimeter90)]

Da eclipse als Tooltip bei einem Mouse-Over über einem Funktionsaufruf 
auch die Doku aus dem c-file (und nur aus diesem) anzeigt ist es so am 
sinnvollsten.

[StinkyWinky (Gast)]

Manchmal benütze ich die Anweisungen "@copydoc" oder "@copydetails", 
wenn ich den gleichen Kommentar an anderer Stelle wieder haben möchte. 
Ob das im konkreten Fall mit der Interface-Doku auch funktioniert, musst 
du selber herausfinden.

[Masl (Gast)]

Man wird natürlich im .c und im .h File Kommentare haben wollen.

Allerdings unterschiedliche Arten von Kommentaren.
Ins .h gehört die Doku zum Interface, also wie der Caller die Funktion 
zu benutzen hat. Ins .h File gehören allerdings keine Internas.

D.h., das "wie" wird im .c File dokumentiert. Denn das "wie" 
interessiert den Caller nicht, wohl aber den Implementeur bzw. 
denjenigen, der in zwei Jahren einen Bug fixen darf.
Ob letztere Art von Kommentar dann in die Doxygen-Doku übernommen werden 
soll ist Ansichtssache, bzw. davon abhängig für wen die Doku gedacht ist 
(User oder Implementeur).

Das Interface im .c File nochmal zu dokumentieren halte ich für unnötig.
Wer einen Editor/IDE aus dem aktuellen Jahrtausend benutzt kann 
hinreichend schnell die Doku aus dem Header nachschlagen.