Kommentieren Sie bei Verwendung von Doxygen mit C den Funktionsprototypen oder die Definition? Oder beides?

Ich verwende Doxygen mit einigen eingebetteten C-Quellen. Fügen Sie bei einem .c/.h-Dateipaar Doxygen-Kommentare zum Funktionsprototyp (.h-Datei) oder zur Funktionsdefinition (.c-Datei) hinzu, oder duplizieren Sie sie an beiden Stellen?

Ich habe ein Problem, bei dem Doxygen vor fehlenden Kommentaren warnt, wenn ich an einer Stelle dokumentiere, aber nicht an der anderen; wird das erwartet, oder ist mein Doxygen vermasselt?

Für öffentliche APIs dokumentiere ich bei der Deklaration, da der Benutzer normalerweise zuerst nachschaut, wenn er nicht die doxygen-Ausgabe verwendet.

Ich hatte nie Probleme damit, nur an einer Stelle zu dokumentieren, aber ich habe es mit C++ verwendet; könnte bei C anders sein, obwohl ich das bezweifle.

[edit] Schreib es nie zweimal. Niemals. Die In-Source-Dokumentation folgt auch DRY, insbesondere in Bezug auf solche Copy-and-Paste-Perversionen.[/edit]

Sie können jedoch angeben, ob Sie möchten Warnungen für undokumentierte Elemente. Obwohl solche Warnungen theoretisch schön aussehen, sind sie meiner Erfahrung nach schnell eher eine Belastung als eine Hilfe. Alle Funktionen zu dokumentieren ist normalerweise nicht der richtige Weg (es gibt so etwas wie redundante Dokumentation oder sogar behindernde Dokumentation und insbesondere zu viel Dokumentation); Eine gute Dokumentation braucht eine sachkundige Person, die sich damit beschäftigt. In Anbetracht dessen sind diese Warnungen unnötig.

Und wenn Sie nicht die Ressourcen haben, um eine gute Dokumentation zu schreiben (Geld, Zeit, was auch immer …), dann werden diese Warnungen auch nicht helfen.

Zitiert aus meiner Antwort auf diese Frage: Dokumentation der C/C++ Header-Datei:

Ich habe Dokumentation für die Schnittstelle (Parameter, Rückgabewert, was die Funktion tut) in der Schnittstellendatei (.h) und die Dokumentation für die Implementierung (wie die Funktion tut) in der Implementierungsdatei (.c, .cpp, .m). Ich schreibe eine Übersicht über die Klasse kurz vor ihrer Deklaration, damit der Leser sofort grundlegende Informationen hat.

Bei Doxygen bedeutet dies, dass eine Dokumentation, die Übersicht, Parameter und Rückgabewerte beschreibt (\brief, \param, \return) dienen der Dokumentation von Funktionsprototypen und der Inline-Dokumentation (\details) wird zum Dokumentieren des Funktionskörpers verwendet (Sie können sich auch auf meine Antwort auf diese Frage beziehen: Wie kann man Kommentare aus einer Funktion in Doxygen extrahieren?)

Ich verwende oft Doxygen mit C, das auf eingebettete Systeme abzielt. Ich versuche, die Dokumentation für jedes einzelne Objekt nur an einer Stelle zu schreiben, weil es zu Duplikaten kommt Wille später zu Verwirrung führen. Doxygen führt ein gewisses Maß an Zusammenführung der Dokumente durch, sodass es im Prinzip möglich ist, die öffentliche API in der zu dokumentieren .h Datei, und um einige Notizen darüber zu haben, wie es tatsächlich funktioniert, in die eingestreut .c Datei. Ich habe versucht, das selbst nicht zu tun.

Wenn das Verschieben der Dokumente von einem Ort zum anderen die Anzahl der erzeugten Warnungen ändert, kann dies ein Hinweis darauf sein, dass sich die Deklaration und die Definition geringfügig unterscheiden. Wird der Code beispielsweise mit -Wall -Wextra sauber kompiliert? Gibt es Makros, die den Code an einer Stelle verändern und an der anderen nicht? Natürlich ist der Parser von Doxygen kein vollständiger Sprachparser, und es ist auch möglich, ihn zu verwirren.

Wir kommentieren nur die Funktionsdefinitionen, aber wir verwenden es mit C++.
Das Schreiben an beiden Stellen ist Zeitverschwendung. Über die Warnung: Wenn Ihre Dokumentation gut aussieht, ist es vielleicht eine gute Möglichkeit, solche Warnungen zu ignorieren.

Ich habe mir dieselbe Frage gestellt und war angenehm überrascht zu sehen, dass Doxygen beim Durchsuchen der generierten HTML-Dokumentation tatsächlich dieselbe Inline-Dokumentation enthält, die in der .c-Datei in der entsprechenden .h-Datei enthalten ist. Daher müssen Sie Ihre Inline-Dokumentation nicht wiederholen, und Doxygen ist schlau genug, sie an beiden Stellen einzufügen!

Ich verwende Version Doxygen Version 1.8.10.