Doxygen C++ Konventionen

Question

Ich stehe am Anfang eines C++-Projekts und habe von Anfang an Doxygen verwendet.

Ich würde gerne wissen, wie Sie Doxygen in Ihrem Projekt verwenden, d.h. ich habe mehrere Fragen:

1. Wo setzen Sie Ihre Doxygen-Kommentare ein? Im Header oder in den Quellen?

Ich denke, sie sollten in den Header gehen, denn dort schaue ich nach, um herauszufinden, wie Methoden verwendet werden. Allerdings lasse ich gerne tatsächliche Parameterbezeichnungen in Prototypen weg, sodass ich @param nicht verwenden kann - oder doch? Wie gehen Sie damit um?

2. Dokumentieren Sie alle Methoden?

Ich dokumentiere bisher nur öffentliche Methoden, wie machen Sie das? Dokumentieren Sie Zugriffsmethoden und öffentliche Variablen?

3. Füllen Sie immer @param und @return aus?

An meinem Arbeitsplatz (es handelt sich um Javadoc, aber es geht um dieselbe Frage) haben wir die Konvention, nur tatsächlich benötigte Eigenschaften auszufüllen, d.h. wenn die Kurzbeschreibung lautet "Gibt xys zurück, wenn ...", lassen wir @return weg. Wenn die Parameterbezeichnungen offensichtlich sind, lassen wir sie weg. Ich bin mir immer noch nicht sicher, ob mir dieser Ansatz gefällt, wie machen Sie das? Bisher habe ich nur die Kurzbeschreibung und nichts weiter ausgefüllt, aber nicht alle Methoden-Prototypen sind dafür unkompliziert genug.

4. Welchen Stil verwenden Sie?

Es gibt verschiedene Stile in Doxygen: Javadoc (/** ... /), QT (/! ... */) und mehr. Rein aus Interesse: Welchen verwenden Sie? Ich benutze derzeit den Javadoc-Stil, weil ich daran gewöhnt bin.

Answer 1

1. Wo platzieren Sie Ihre Doxygen-Kommentare? Im Header oder in den Quellen?

Ich kann das nicht beantworten, weil ich mich tatsächlich gerade nicht daran erinnere, wo ich normalerweise in Bezug auf Header versus Quelle dokumentiere.

2. Dokumentieren Sie alle Methoden?

Fast vollständig ja. Jede einzelne Methode erhält irgendeine Form von Dokumentation, es sei denn, es ist sofort offensichtlich aus dem Variablennamen/Methode-namen (und den Parameter-Namen für Methoden), was sie spezifisch tut. Ich gehe nach der Regel "Wenn Sie den Zweck einer Methode nicht am Namen und den Parameter-Namen erkennen können, benötigt sie einen Kommentar. Wenn Sie nach dem Kommentieren immer noch nicht den Zweck der Methode erkennen können, schreiben Sie den Kommentar neu. Wenn Sie immer noch nicht sehr schnell den Zweck der Methode erkennen können, oder wenn der Kommentar 'zu lang' ist (wobei 'zu lang' eine willkürliche Messung ist >_>), dann müssen Sie die Methode neu schreiben oder aufteilen."

3. Füllen Sie immer @param und @return aus?

Ja. Selbst wenn es beim Lesen des @brief offensichtlich ist, oder wenn das @return ein exakter Satz aus dem @brief ist, fülle ich sie immer aus. Es kann sehr nützlich sein, diese Art von Schnelleigenschaft für die Dokumentation einer Methode zu haben. "Oh, Methode X, ich weiß, was sie tut und warum, aber was genau ist ihr Rückgabewert in Situation X wieder?" *überprüft das @return*.

4. Welchen Stil verwenden Sie?

Ich benutze den Javadoc-Stil, obwohl das vollkommen subjektiv ist. Ich benutze die Javadoc-Syntax, weil ich eine Weile in Java geschrieben habe und sehr an diese Syntax gewöhnt bin. Ich persönlich finde auch, dass sie sinnvoller ist als die anderen – ich mag den QT-Syntax überhaupt nicht.

Answer 2

1. Wo platzieren Sie Ihre Doxygen-Kommentare? Header oder Quellen?

Die Dokumentation wird in den Headern platziert, da hier die Schnittstelle definiert ist.

2. Dokumentieren Sie alle Methoden?

Bei Klassen dokumentiere ich alle öffentlichen und geschützten Methoden, private Methoden lasse ich in der Regel aus.

3. Füllen Sie immer @param und @return aus?

Ich ziehe die Inline-Parameterdokumentation vor.

/*!
 * \brief Meine großartige Klasse.
 */
class Foo
{
public:
    /*!
     * \brief Meine großartige Methode.
     */
    void method(
        int parameter    //!< [in] Der Parameter tut etwas großartiges
    );
};

anstelle von \param, da es zu einer Duplizierung des Parameternamens führt und leicht aus dem Code herauskommen kann, wenn faule Entwickler vergessen, den Doxygen zu ändern.

\return wird weggelassen, wenn der Rückgabetyp void ist. Ich verwende immer \throw, wenn die Methode eine Ausnahme werfen kann.

4. Welchen Stil verwenden Sie?

Es ist egal, solange er im gesamten Projekt konsistent ist.