Стиль документации C++

Для генерации документации QDoc проходит по исходному коду и генерирует документацию для типов C++, таких как классы. QDoc затем связывает методы-члены, свойства и другие типы с соответствующим классом.

Обратите внимание, что документация должна быть в файлах реализации, таких как .cpp.

Документация класса

Документация класса генерируется с помощью команды \class и имени класса в качестве первого аргумента.

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

    \sa QPixmapCache, QHash, QMap
*/

Команды контекста добавляют информацию о классе, такую как его модуль или версия, в которую был добавлен класс.

Некоторые распространённые команды контекста:

• \brief - краткое описание класса (обязательно)
• \since - версия, к которой был добавлен класс (обязательно)
• \internal - отмечает класс как внутренний. Внутренние классы не отображаются в общедоступной документации API.

Краткое и подробное описание

Краткое описание отмечено командой \brief и предназначено для краткого изложения цели или функциональности класса. Для классов C++ QDoc возьмёт класс и создаст аннотированную информацию для него. Аннотированная информация отображается в списках и таблицах, которые отображают класс.

Краткое описание на C++ должно начинаться с:

"The <C++ class name> class"

Раздел Подробное описание начинается после краткого описания. Он предоставляет более подробную информацию о классе. Подробное описание может содержать изображения, фрагменты кода или ссылки на другие соответствующие документы. Должна быть пустая строка, разделяющая краткое и подробное описание.

Члены-функции

Обычно документация функции непосредственно предшествует реализации функции в файле .cpp. Для документации функции, которая не находится непосредственно над реализацией, требуется \fn.

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

Документация функции начинается с глагола, указывающего операцию, которую выполняет функция. Это также относится к конструкторам и деструкторам.

Некоторые общие глаголы для документации функций:

• "Создаёт..." - для конструкторов
• "Уничтожает..." - для деструкторов
• "Возвращает..." - для функций-акцессоров

Документация функции должна документировать:

• тип возвращаемого значения
• параметры
• действия функций

Команда \a отмечает параметр в документации. Документация типа возвращаемого значения должна ссылаться на документацию типа или быть отмечена командой \c в случае булевых значений.

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

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

Свойства

Документация свойства находится непосредственно над реализацией функции чтения. Команда темы для свойств — \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

Документация свойства обычно начинается с «Это свойство...», но возможны и альтернативные выражения:

• "Это свойство содержит..."
• "Это свойство описывает..."
• "Это свойство представляет..."
• "Возвращает true при... и false при..." — для свойств, которые читаются.
• "Устанавливает..." — для свойств, которые конфигурируют тип.

Документация свойства должна включать:

• описание и поведение свойства
• допустимые значения свойства
• значение свойства по умолчанию

Аналогично функциям функций, тип по умолчанию может быть связан или помечен командой \c.

Пример стиля диапазона значений:

Значения изменяются от 0,0 (нет размытия) до maximumRadius (максимальное размытие). По умолчанию свойство устанавливается в 0,0 (нет размытия).

Сигналы, уведомления и слоты

Команда темы для сигналов, уведомлений и слотов — \fn. Документация сигналов указывает, когда они срабатывают или излучаются.

/*!
  \fn QAbstractTransition::triggered()

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

Документация сигналов обычно начинается с «Этот сигнал срабатывает при...». Вот альтернативные стили:

• "Этот сигнал срабатывает при..."
• "Срабатывает при..."
• "Выполняется при..."

Для слотов или уведомлений должна быть задокументирована ситуация, когда они выполняются или вызываются сигналом.

• "Выполняется при..."
• "Этот слот выполняется при..."

Для свойств, имеющих перегруженные сигналы, QDoc группирует перегруженные уведомления вместе. Чтобы сослаться на определённую версию уведомления или сигнала, достаточно сослаться на свойство и упомянуть, что существует несколько версий уведомления.

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

Перечисления, пространства имён и другие типы

Перечисления, пространства имён и макросы имеют команду темы для своей документации:

• \enum
• \typedef
• \macro

Стиль языка для этих типов указывает, что это перечисление или макрос, и продолжает описание типа.

Для перечислений команда \value используется для перечисления значений. QDoc создаёт таблицу значений для перечисления.

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