Wohin mit den Doxygen Kommentarblöcken für eine interne Bibliothek - in H oder in CPP-Dateien?

Question

Der gesunde Menschenverstand sagt, dass die Doxygen-Kommentarblöcke in die Header-Dateien geschrieben werden müssen, in denen sich die Klassen, Strukturen, Aufzählungen, Funktionen und Deklarationen befinden. Ich stimme zu, dass dies ein solides Argument für eine Bibliothek ist, die ohne ihre Quelle verteilt werden soll (nur Header und Bibliotheken mit Objektcode).

ABER ... Ich habe über das genaue Gegenteil nachgedacht, wenn ich eine interne zu der Firma (oder als ein Nebenprojekt für mich selbst) Bibliothek entwickle, die mit seinem vollen Quellcode benutzt wird. Was ich vorschlage, ist, die großen Kommentarblöcke in die Implementierungsdateien (HPP, INL, CPP usw.) zu setzen, um NICHT die Oberfläche der Klassen und Funktionen zu verwerfen, die im Header deklariert sind.

Pro:

• Weniger Unordnung in den Header-Dateien können nur Kategorisieren der Funktionen hinzugefügt werden.
• Die Kommentarblöcke, die in der Vorschau angezeigt werden, wenn Intellisense zum Beispiel verwendet wird, kollidiert nicht - das ist ein Fehler, den ich beobachtet habe, wenn ich einen Kommentarblock für eine Funktion in der .H-Datei habe und seine Inline-Definition habe .H-Datei, aber aus der .INL-Datei enthalten.

Nachteile:

• (Die offensichtlichste) Die Kommentarblöcke sind nicht in den Header-Dateien, in denen die Erklärungen sind.

Also, was denkst du und möglicherweise vorschlagen?

Answer 1

Legen Sie die Dokumentation, in der die Benutzer sie lesen und schreiben, während sie den Code verwenden und bearbeiten.

Klassenkommentare gehen vor Klassen, Methodenkommentare vor Methoden.

Das ist der beste Weg, um sicherzustellen, dass die Dinge erhalten bleiben. Es hält auch Ihre Header-Dateien relativ schlank und vermeidet die berühren Problem der Menschen Methode Methode Docs verursacht Header schmutzig zu sein und die Wiederherstellung auslöst. Ich habe tatsächlich gewusst, dass Leute das als Entschuldigung für das Schreiben von Dokumentation verwenden später!

Answer 2

Header: Leichter zu lesen die Kommentare, da gibt es weniger andere "Lärm" beim Betrachten der Dateien.

Quelle: Dann haben Sie die tatsächlichen Funktionen zum Lesen und betrachten Sie die Kommentare.

Wir verwenden nur alle globalen Funktionen kommentiert in den Kopfzeilen und lokalen Funktionen in der Quelle kommentiert. 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 . Z.B. : -

Mein file1.h

/** 
* \brief Short about function 
* 
* More about function 
*/ 
WORD my_fync1(BYTE*); 

MY file1.c

/** \copydoc my_func1 */ 
WORD my_fync1(BYTE* data){/*code*/} 

Jetzt erhalten Sie die gleiche Dokumentation zu beiden Funktionen.

Dies gibt Ihnen weniger Lärm in den Code-Dateien zur gleichen Zeit, wenn Sie die Dokumentation an einer Stelle geschrieben an mehreren Stellen in der endgültigen Ausgabe erhalten.

Answer 3

Normalerweise habe ich Dokumentation für Schnittstelle (\ param, \ return) in .h-Datei und Dokumentation für die Implementierung (\ Details) in .c/.cpp/.m-Datei. Doxygen gruppiert alles in der Funktions-/Methodendokumentation.

Answer 4

Ich habe alles in die Header-Datei.

Ich dokumentiere alles, aber extrahiere nur allgemein die öffentliche Schnittstelle.

Answer 5

Kommentare in der Kopfzeile bedeutet, dass alle Benutzer einer Klasse neu kompiliert werden müssen, wenn ein Kommentar geändert wird. Bei großen Projekten sind die 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 für die Dokumentation durchsuchen sollten, ist es kein großes Problem, dass die Kommentarblöcken in den Quelldateien schwieriger zu finden sind.

Answer 6

Ich nutze gerne die Tatsache, dass Namen an mehreren Stellen dokumentiert werden können.

In der Header-Datei, schreibe ich eine kurze Beschreibung der Methode, und dokumentieren Sie alle ihre Parameter - diese sind weniger wahrscheinlich zu ändern als die Implementierung der Methode selbst, und wenn sie es tun, dann muss die Funktion Prototyp sein auf jeden Fall geändert.

Ich lege Dokumentationen mit langem Format in die Quelldateien neben der eigentlichen Implementierung, sodass die Details bei der Entwicklung der Methode geändert werden können.

Zum Beispiel:

mymodule.h

/// @brief This method adds two integers. 
/// @param a First integer to add. 
/// @param b Second integer to add. 
/// @return The sum of both parameters. 
int add(int a, int b); 

mymodule.cpp

/// This method uses a little-known variant of integer addition known as 
/// Sophocles' Scissors. It optimises the function's performance on many 
/// platforms that we may or may not choose to target in the future. 
/// @TODO make sure I implemented the algorithm correctly with some unit tests. 
int add(int a, int b) { 
    return b + a; 
} 

Answer 7

Ich verwende QtCreator für die Programmierung. Ein sehr nützlicher Trick besteht darin, dass Sie bei gedrückter Strg-Taste auf eine Funktion oder Methode klicken, um die Deklaration in der Header-Datei abzurufen.

Wenn die Methode in der Headerdatei kommentiert ist, können Sie die gewünschten Informationen schnell finden. Für mich sollten Kommentare also in der Header-Datei stehen!

Answer 8

In C++ manchmal kann die Implementierung zwischen Header und .cpp Module aufgeteilt werden. Hier scheint es sauberer zu sein, die Dokumentation in die Header-Datei zu schreiben, da dies der einzige Ort ist, an dem alle öffentlichen Funktionen und Methoden garantiert sind.