C++-Dokumentationsstil

Zur Erstellung der Dokumentation durchläuft QDoc den Quellcode und generiert Dokumentation für C++-Typen wie beispielsweise Klassen. Anschließend ordnet QDoc Mitgliedsfunktionen, Eigenschaften und andere Typen der entsprechenden Klasse zu.

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

Klassendokumentation

Die Klassendokumentation wird mithilfe des \class Befehl und den Namen der Klasse als erstes Argument generiert.

/*!
    \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 zur 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 (erforderlich)
• \since - die Version, in der die Klasse hinzugefügt wurde (obligatorisch)
• \internal - Kennzeichnet die Klasse als intern. Interne Klassen erscheinen nicht in der öffentlichen API-Dokumentation.

Die kurze und die ausführliche Beschreibung

Die Kurzbeschreibung wird mit dem Befehl \brief Befehl und dient dazu, den Zweck oder die Funktionalität der Klasse zusammenzufassen. Bei C++-Klassen erstellt QDoc anhand der Klasse kommentierte Informationen für die Klasse. Die kommentierten Informationen erscheinen in Listen und Tabellen, in denen die Klasse dargestellt wird.

Die kurze Beschreibung in C++ sollte wie folgt beginnen:

"The <C++ class name> class"

Der Abschnitt mit der ausführlichen Beschreibung beginnt nach der kurzen Beschreibung. Er liefert weitere Informationen über die Klasse. Die ausführliche Beschreibung kann Bilder, Codeausschnitte oder Links zu anderen relevanten Dokumenten enthalten. Zwischen der kurzen und der ausführlichen Beschreibung muss eine Leerzeile stehen.

Member-Funktionen

In der Regel steht die Funktionsdokumentation unmittelbar vor der Implementierung der Funktion in der Datei „ .cpp “. Für Funktionsdokumentation, die nicht unmittelbar über der Implementierung steht, ist das \fn erforderlich.

/*!
  \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 von der Funktion ausgeführte Operation angibt. Dies gilt auch für Konstruktoren und Destruktoren.

Einige gängige Verben für die Funktionsdokumentation:

• „Erstellt...“ – für Konstruktoren
• „Zerstört …“ – für Destruktoren
• „Gibt … zurück“ – für Zugriffsfunktionen

Die Funktionsdokumentation muss Folgendes dokumentieren:

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

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

/*!
    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 Eigenschaftsdokumentation befindet sich unmittelbar über der Implementierung der Lesefunktion. Der Befehl „topic“ 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 Eigenschaftsdokumentation beginnt in der Regel mit „Diese Eigenschaft…“, es gibt jedoch auch alternative Formulierungen:

• „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 den …“ – für Eigenschaften, die einen Typ konfigurieren.

Die Dokumentation einer Eigenschaft muss Folgendes enthalten:

• eine Beschreibung und das Verhalten der Eigenschaft
• zulässige 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 (keine Unschärfe) bis zu „maximalRadius“ (maximale Unschärfe). Standardmäßig ist die Eigenschaft auf 0,0 (keine Unschärfe) gesetzt.

Signale, Notifier und Slots

Der Befehl „topic“ für Signale, Notifier und Slots lautet \fn. In der Dokumentation von Signalen wird angegeben, wann sie ausgelöst oder ausgesendet werden.

/*!
  \fn QAbstractTransition::triggered()

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

Die Dokumentation von Signalen beginnt typischerweise mit „Dieses Signal wird ausgelöst, wenn...“. Hier sind alternative Stile:

• „Dieses Signal wird ausgelöst, wenn…“
• „Ausgelöst, wenn …“
• „Ausgelöst, wenn …“

Bei Slots oder Notifiern sollte die Bedingung dokumentiert werden, unter der sie ausgeführt oder durch ein Signal ausgelöst werden.

• „Ausgeführt, wenn …“
• „Dieser Slot wird ausgeführt, wenn ...“

Bei Eigenschaften mit überladenen Signalen fasst QDoc die überladenen Notifier zusammen. Um auf eine bestimmte Version eines Notifiers oder Signals hinzuweisen, verweisen Sie einfach auf die Eigenschaft und erwähnen Sie, 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 verfügen über einen Themenbefehl für ihre Dokumentation:

• \enum
• \typedef
• \macro

Der Sprachstil für diese Typen weist darauf hin, dass es sich um eine Enumeration oder ein Makro handelt, und fährt mit der Typbeschreibung fort.

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

/*!
    \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.
*/