Stil der C++-Dokumentation

Um die Dokumentation zu generieren, geht QDoc durch den Quellcode und generiert die Dokumentation für C++-Typen wie z.B. Klassen. QDoc assoziiert dann Mitgliedsfunktionen, Eigenschaften und andere Typen mit der entsprechenden Klasse.

Beachten Sie, dass sich die Dokumentation in den Implementierungsdateien wie .cpp befinden muss.

Klassendokumentation

Klassendokumentation wird mit dem Befehl \class und dem Namen der Klasse als erstem Argument erzeugt.

/*!
    \class QCache
    \brief The QCache class is a template class that provides a cache.

    \ingroup tools
    \ingroup shared

    \reentrant

    QCache\<Key, T\> defines a cache that stores objects of type T
    associated with keys of type Key. For example, here's the
    definition of a cache that stores objects of type Employee
    associated with an integer key:

    \snippet code/doc_src_qcache.cpp 0

    Here's how to insert an object in the cache:

    \snippet code/doc_src_qcache.cpp 1

    ... detailed description omitted

    \sa QPixmapCache, QHash, QMap
*/

Kontextbefehle fügen Informationen über die Klasse hinzu, wie z. B. ihr Modul oder die Version, in der die Klasse hinzugefügt wurde.

Einige gängige Kontextbefehle sind:

• \brief - die Kurzbeschreibung der Klasse (obligatorisch)
• \since - die Version, zu der die Klasse hinzugefügt wurde (obligatorisch)
• \internal - kennzeichnet die Klasse als intern. Interne Klassen erscheinen nicht in der öffentlichen API-Dokumentation.

Die Kurz- und Detailbeschreibung

Die Kurzbeschreibung ist mit dem Befehl \brief gekennzeichnet und dient dazu, den Zweck oder die Funktionalität der Klasse zusammenzufassen. Für C++ Klassen nimmt QDoc die Klasse und erstellt kommentierte Informationen für die Klasse. Die kommentierten Informationen erscheinen in Listen und Tabellen, die die Klasse darstellen.

Die C++ Kurzbeschreibung sollte mit beginnen:

"The <C++ class name> class"

Der Abschnitt mit der detaillierten Beschreibung beginnt nach der Kurzbeschreibung. Er enthält weitere Informationen über die Klasse. Die ausführliche Beschreibung kann Bilder, Codeschnipsel oder Links zu anderen relevanten Dokumenten enthalten. Zwischen der Kurzbeschreibung und der ausführlichen Beschreibung muss eine Leerzeile stehen.

Mitgliedsfunktionen

Normalerweise steht die Funktionsdokumentation unmittelbar vor der Implementierung der Funktion in der Datei .cpp. Für die Funktionsdokumentation, die nicht unmittelbar über der Implementierung steht, wird das \fn benötigt.

/*!
  \fn QString &QString::remove(int position, int n)

  Removes \a n characters from the string, starting at the given \a
  position index, and returns a reference to the string.

  If the specified \a position index is within the string, but \a
  position + \a n is beyond the end of the string, the string is
  truncated at the specified \a position.

  \snippet qstring/main.cpp 37

  \sa insert(), replace()
*/
QString &QString::remove(int pos, int len)

Die Funktionsdokumentation beginnt mit einem Verb, das die Operation angibt, die die Funktion ausführt. Dies gilt auch für Konstruktoren und Destruktoren.

Einige übliche Verben für die Funktionsdokumentation:

• "Constructs..." - für Konstruktoren
• "Zerstört..." - für Destruktoren
• "Gibt zurück..." - für Accessor-Funktionen

Die Funktionsdokumentation muss dokumentieren:

• den Rückgabetyp
• die Parameter
• die Aktionen der Funktionen

Der Befehl \a kennzeichnet den Parameter in der Dokumentation. Die Dokumentation des Rückgabetyps sollte auf die Dokumentation des Typs verweisen oder im Falle von booleschen Werten mit dem Befehl \c gekennzeichnet sein.

/*!
    Returns \c true if a QScroller object was already created for \a target; \c false otherwise.

    \sa scroller()
*/
bool QScroller::hasScroller(QObject *target)

Eigenschaften

Die Dokumentation der Eigenschaften befindet sich unmittelbar über der Implementierung der Lesefunktion. Der Topic-Befehl für Eigenschaften lautet \property.

/*!
    \property QVariantAnimation::duration
    \brief the duration of the animation

    This property describes the duration in milliseconds of the
    animation. The default duration is 250 milliseconds.

    \sa QAbstractAnimation::duration()
 */
int QVariantAnimation::duration() const

Die Dokumentation von Eigenschaften beginnt in der Regel mit "Diese Eigenschaft...", aber es gibt auch andere Ausdrücke:

• "Diese Eigenschaft enthält..."
• "Diese Eigenschaft beschreibt..."
• "Diese Eigenschaft repräsentiert..."
• "Gibt true zurück, wenn... und false, wenn..." - für Eigenschaften, die gelesen werden.
• "Setzt die..." - für Eigenschaften, die einen Typ konfigurieren.

Die Dokumentation der Eigenschaft muss Folgendes enthalten:

• Beschreibung und Verhalten der Eigenschaft
• akzeptierte Werte für die Eigenschaft
• den Standardwert der Eigenschaft

Ähnlich wie bei Funktionen kann der Standardtyp mit dem Befehl \c verknüpft oder markiert werden.

Ein Beispiel für einen Wertebereichsstil ist:

Die Werte reichen von 0.0 (kein Weichzeichner) bis maximumRadius (maximaler Weichzeichner). Standardmäßig ist die Eigenschaft auf 0,0 (keine Unschärfe) eingestellt.

Signale, Melder und Steckplätze

Der Themenbefehl für Signale, Melder und Slots lautet \fn. Die Dokumentation von Signalen gibt an, wann sie ausgelöst oder ausgegeben werden.

/*!
  \fn QAbstractTransition::triggered()

  This signal is emitted when the transition has been triggered (after
  onTransition() has been called).
*/

Signaldokumentationen beginnen normalerweise mit "Dieses Signal wird ausgelöst, wenn...". Hier sind alternative Stile:

• "Dieses Signal wird ausgelöst, wenn..."
• "Ausgelöst, wenn..."
• "Ausgegeben, wenn..."

Für Slots oder Melder sollte die Bedingung dokumentiert werden, wann sie ausgeführt oder durch ein Signal ausgelöst werden.

• "Ausgeführt, wenn..."
• "Dieser Slot wird ausgeführt, wenn..."

Für Eigenschaften, die überladene Signale haben, fasst QDoc die überladenen Melder zusammen. Um sich auf eine bestimmte Version eines Notifiers oder Signals zu beziehen, verweist man einfach auf die Eigenschaft und erwähnt, dass es verschiedene Versionen des Notifiers gibt.

/*!
\property QSpinBox::value
\brief the value of the spin box

setValue() will emit valueChanged() if the new value is different
from the old one. The \l{QSpinBox::}{value} property has a second notifier
signal which includes the spin box's prefix and suffix.
*/

Enums, Namespaces und andere Typen

Enums, Namespaces und Makros haben einen Topic-Befehl für ihre Dokumentation:

• \enum
• \typedef
• \macro

Der Sprachstil für diese Typen erwähnt, dass es sich um eine Aufzählung oder ein Makro handelt, und fährt mit der Typbeschreibung fort.

Bei Aufzählungen dient der Befehl \value der Auflistung der Werte. QDoc erstellt eine Wertetabelle für die Aufzählung.

/*!
    \enum QSql::TableType

    This enum type describes types of SQL tables.

    \value Tables  All the tables visible to the user.
    \value SystemTables  Internal tables used by the database.
    \value Views  All the views visible to the user.
    \value AllTables  All of the above.
*/