Der gesunde Menschenverstand sagt, dass die Doxygen-Kommentarblöcke in die Header-Dateien eingefügt werden müssen, in denen sich die Klassen, Strukturen, Aufzählungen, Funktionen und Deklarationen befinden. Ich bin damit einverstanden, dass dies ein gutes Argument für Bibliotheken ist, die ohne ihre Quelle verteilt werden sollen (nur Header und Bibliotheken mit Objektcode).
ABER ... Ich habe über den genau entgegengesetzten Ansatz nachgedacht, als ich eine unternehmensinterne (oder als Nebenprojekt für mich selbst) Bibliothek entwickelt habe, die mit ihrem vollständigen Quellcode verwendet wird. Ich schlage vor, die großen Kommentarblöcke in die Implementierungsdateien (HPP, INL, CPP usw.) einzufügen, um die Schnittstelle der im Header deklarierten Klassen und Funktionen NICHT zu überladen.
Vorteile:
- Weniger Unordnung in den Header-Dateien, nur eine Kategorisierung der Funktionen kann hinzugefügt werden.
- Die Kommentarblöcke, die bei Verwendung von Intellisense in der Vorschau angezeigt werden, kollidieren nicht. Dies ist ein Fehler, den ich festgestellt habe, wenn ich einen Kommentarblock für eine Funktion in der .H-Datei habe und dessen Inline-Definition in derselben .H-Datei liegt aber aus der INL-Datei enthalten.
Nachteile:
- (Der offensichtliche) Die Kommentarblöcke befinden sich nicht in den Header-Dateien, in denen sich die Deklarationen befinden.
Also, was denkst du und schlägst du möglicherweise vor?
quelle
Ich nutze gerne die Tatsache, dass Namen an mehreren Stellen dokumentiert werden können.
In die Header-Datei schreibe ich eine kurze Beschreibung der Methode und dokumentiere alle ihre Parameter - diese ändern sich weniger wahrscheinlich als die Implementierung der Methode selbst, und wenn dies der Fall ist, muss der Funktionsprototyp auf jeden Fall geändert werden .
Ich habe langformatige Dokumentation in die Quelldateien neben der eigentlichen Implementierung eingefügt, damit die Details im Verlauf der Methode geändert werden können.
Beispielsweise:
mymodule.h
mymodule.cpp
quelle
Kommentare in der Kopfzeile bedeuten, dass alle Benutzer einer Klasse neu kompiliert werden müssen, wenn ein Kommentar geändert wird. Bei großen Projekten sind Programmierer weniger geneigt, Kommentare in Kopfzeilen zu aktualisieren, wenn sie die nächsten 20 Minuten damit verbringen, alles neu zu erstellen.
Und ... da Sie das HTML-Dokument lesen und nicht den Code nach Dokumentation durchsuchen sollen, ist es kein großes Problem, dass die Kommentarblöcke in den Quelldateien schwieriger zu finden sind.
quelle
Überschriften: Einfacheres Lesen der Kommentare, da beim Betrachten der Dateien weniger andere "Geräusche" auftreten.
Quelle: Dann stehen Ihnen die eigentlichen Funktionen zum Lesen zur Verfügung, während Sie sich die Kommentare ansehen.
Wir verwenden nur alle globalen Funktionen, die in Headern kommentiert sind, und lokale Funktionen, die in der Quelle kommentiert sind. Wenn Sie möchten, können Sie auch den Befehl copydoc einfügen, um die Dokumentation an mehreren Stellen einzufügen, ohne sie mehrmals schreiben zu müssen (besser für die Wartung).
Sie können die Ergebnisse jedoch auch mit einem einfachen Befehl in eine andere Dateidokumentation kopieren lassen. Z.B :-
Meine Datei1.h
MEINE Datei1.c
Jetzt erhalten Sie für beide Funktionen die gleiche Dokumentation.
Dies gibt Ihnen weniger Rauschen in den Codedateien, während Sie die Dokumentation an einer Stelle schreiben lassen, die an mehreren Stellen in der endgültigen Ausgabe dargestellt wird.
quelle
Normalerweise füge ich die Dokumentation für die Schnittstelle (\ param, \ return) in die .h-Datei und die Dokumentation für die Implementierung (\ details) in die .c / .cpp / .m-Datei ein. Doxygen gruppiert alles in der Funktions- / Methodendokumentation.
quelle
Ich habe alles in die Header-Datei eingefügt.
Ich dokumentiere alles, extrahiere aber generell nur die öffentliche Schnittstelle.
quelle
Ich benutze QtCreator zum Programmieren. Ein sehr nützlicher Trick besteht darin, bei gedrückter Strg-Taste auf eine Funktion oder Methode zu klicken, um die Deklaration in der Header-Datei abzurufen.
Wenn die Methode in der Header-Datei kommentiert ist, können Sie die gesuchten Informationen schnell finden. Für mich sollten sich Kommentare in der Header-Datei befinden!
quelle
In c ++ kann die Implementierung manchmal zwischen Header- und CPP-Modulen aufgeteilt werden. Hier scheint es sauberer, die Dokumentation in die Header-Datei einzufügen, da dies der einzige Ort ist, an dem alle öffentlichen Funktionen und Methoden garantiert sind.
quelle