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:
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.
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...
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.
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..?
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.
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.
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.
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.
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.
Eine eigene Frage?
Dieser Thread ist über 12 Jahre alt.
Stell sie in einem eigenen Thread – dort lesen mehr Leute mit, und sie wird öfter und schneller beantwortet.