Ich stehe am Anfang eines C ++ Projekts und benutze Doxygen von Anfang an.
Ich würde gerne wissen, wie Sie Doxygen in Ihrem Projekt verwenden, d. h. ich habe mehrere Fragen:
1. Wo setzt du deine Doxygen-Kommentare ab? Kopfzeile oder Quellen?
Ich denke, dass sie zum Header gehen sollten, weil ich dort herausfinden möchte, wie man Methoden benutzt. Ich möchte jedoch die eigentlichen Parameternamen in Prototypen auslassen, so dass ich @param nicht verwenden kann - oder kann ich? Wie gehst du damit um?
2. Dokumentieren Sie alle Methoden?
Ich dokumentiere bisher nur öffentliche Methoden, wie machst du das? Dokumentieren Sie Accessor-Methoden und öffentliche Variablen?
3. Füllen Sie immer @param und @return aus?
Wo ich arbeite (es ist Javadoc, aber es ist das gleiche Problem), haben wir eine Konvention, um nur die tatsächlich benötigten Eigenschaften zu füllen, d. h. wenn die kurze Beschreibung "Returns xys if ..." sagt, lassen wir @return aus. Wenn die Parameternamen offensichtlich sind, lassen wir sie weg. Ich bin mir immer noch nicht sicher, ob ich diesen Ansatz mag, wie machst du das? Bis jetzt habe ich nur den Auftrag und nichts anderes ausgefüllt, aber nicht alle Methodenprototypen sind einfach genug dafür.
4. Welchen Stil verwendest du?
Es gibt verschiedene Stile in Doxygen: Javadoc (/ ** ... /), QT (/ ! ... * /) und mehr. Nur aus Interesse: Welchen benutzen Sie? Ich gehe mit Javadoc-Stil ATM, weil ich daran gewöhnt bin.
Ich kann 1 nicht beantworten, weil ich mich momentan nicht daran erinnere, wo ich in Bezug auf Header vs Quelle tendiere. Aber wie für die anderen:
2. Dokumentieren Sie alle Methoden?
Fast vollständig ja. Jede einzelne Methode erhält eine Art von Dokumentation, es sei denn, ist sofort aus dem Namen der Variablen / Methode (und den Parameternamen für Methoden) ersichtlich, was sie in den Einzelheiten tut. Ich tendiere dazu, nach der Regel zu gehen: "Wenn man den Zweck einer Methode nicht anhand ihrer Namen und Parameternamen herausfinden kann, benötigt sie einen Kommentar. Wenn Sie nach dem Kommentieren den Zweck der Methode noch nicht herausfinden können, schreiben Sie neu Wenn Sie den Zweck der Methode immer noch nicht schnell erkennen können oder der Kommentar zu lang ist (wobei "zu lang" eine willkürliche Messung & gt; _ & gt; ist), müssen Sie die Methode neu schreiben oder teile es auf. "
3. Füllen Sie immer @param und @return aus?
Ja. Auch wenn es beim Lesen des Briefes offensichtlich ist, oder wenn @return eine exakte Kopie des Satzes in dem Brief ist, fülle ich sie immer noch aus. Es kann sehr nützlich sein, eine solche Scan-Eigenschaft für die Dokumentation einer Methode zu haben. "Oh, Methode X, ich weiß, was es macht und warum, aber was genau ist sein Rückgabewert in X-Situation wieder?" * Überprüfen Sie die @return *.
4. Welchen Stil verwendest du?
Javadoc selbst, obwohl das völlig subjektiv ist. Ich benutze die Javadoc-Syntax, weil ich eine Weile in Java geschrieben habe und mich an diese Syntax gewöhnt habe. Ich persönlich finde es auch sinnvoller als die anderen - ich mag die QT -Syntax überhaupt nicht.
1. Wo setzt du deine Doxygen-Kommentare ab? Kopfzeile oder Quellen?
Dokumentation geht in Kopfzeilen, da hier die Schnittstelle definiert ist.
2. Dokumentieren Sie alle Methoden?
Für Klassen dokumentiere ich alle öffentlichen und geschützten Methoden, im Allgemeinen belasse ich private Methoden.
3. Füllen Sie immer @param und @return aus?
Ich bevorzuge die Inline-Parameterdokumentation
%Vor% verwendet \param , da dies zu einer Duplizierung des Parameternamens führt und leicht mit dem Code nicht mehr synchron ist, wenn faule Entwickler vergessen, doxygen zu ändern.
\return wird weggelassen, wenn ein void return-Typ vorliegt. Ich verwende immer \throw , wenn die Methode auslösen kann.
4. Welchen Stil verwendest du?
Es spielt keine Rolle, solange es im gesamten Projekt konsistent ist.
Tags und Links c++ doxygen conventions