Написание документации

Комментарии QDoc

Документация содержится в комментариях QDoc, ограниченных /*! и */ комментариями. Обратите внимание, что это допустимые комментарии в C++, QML и JavaScript.

Внутри комментария QDoc используется //! в качестве однострочного комментария документации; сам комментарий и все, что после него, до новой строки, исключаются из сгенерированного вывода.

QDoc будет анализировать файлы C++ и QML, чтобы найти комментарии QDoc. Чтобы явно исключить определенный тип файла, исключите его из файла конфигурации.

Команды QDoc

QDoc использует команды для получения информации о документации. Topic команды определяют тип элемента документации, context команды предоставляют подсказки и информацию о теме, а markup команды предоставляют информацию о том, как QDoc должен форматировать часть документации.

Темы QDoc

Каждый комментарий QDoc должен иметь тип темы. Тема отличает его от других тем. Чтобы указать тип темы, используйте одну из нескольких команд тем.

QDoc соберет похожие темы и создаст страницу для каждой из них. Например, все перечисления, свойства, функции и описание класса определенного класса C++ будут находиться на одной странице. Общая страница указывается с помощью команды \page, а имя файла является аргументом.

Примеры команд тем:

• \enum — для документации перечислений
• \class — для документации класса C++
• \qmltype — для документации типа QML
• \page — для создания страницы.

Один комментарий QDoc может содержать несколько команд тем в одной категории, с некоторыми ограничениями. Таким образом, можно написать один комментарий, который документирует все перегрузки функции (используя несколько \fn команд) или все свойства в группе свойств QML (используя \qmlproperty команды) за один раз.

Если комментарий QDoc содержит несколько команд тем, можно предоставить дополнительные команды контекста для отдельных тем в последующих комментариях:

/*!
    \qmlproperty string Type::element.name
    \qmlproperty int Type::element.id

    \brief Holds the element name and id.
*/

/*!
    \qmlproperty int Type::element.id
    \readonly
*/

Здесь последующий комментарий отмечает свойство element.id как только для чтения, в то время как element.name остается изменяемым.

Примечание: Последующий комментарий не может содержать дополнительный текст, только команды контекста, которые документируют контекст элемента.

Команда \page предназначена для создания статей, которые не являются частью документации исходного кода. Команда также может принимать два аргумента: имя файла статьи и тип документации. Возможные типы:

• howto
• overview
• tutorial
• faq
• attribution — используется для документирования лицензионных атрибутов
• article — по умолчанию, когда тип отсутствует

/*!
    \page altruism-faq.html faq
    \title Altruism Frequently Asked Questions

    \brief All the questions about altruism, answered.

    ...
*/

На странице Команды тем содержится информация обо всех доступных командах тем.

Контексты тем

Команды контекста дают QDoc подсказку о контексте темы. Например, если функция C++ устарела, то она должна быть помечена как устаревшая с помощью команды \obsolete. Аналогично, навигация по страницам и заголовок страницы предоставляют QDoc дополнительную информацию о странице.

QDoc создаст дополнительные ссылки или страницы для этих контекстов. Например, группа создается с помощью команды \group, а члены имеют команду \ingroup. Имя группы предоставляется в качестве аргумента.

На странице Команды контекста представлен список всех доступных команд контекста.

Разметка документации

QDoc может выполнять разметку текста, подобно другим средствам разметки или документирования. QDoc может пометить фрагмент текста жирным шрифтом, когда текст размечается с помощью команды \b.

\b{This} text will be in \b{bold}.

На странице Команды разметки представлен полный список доступных команд разметки.

Структура документации

По существу, для создания страницы QDoc должны быть присутствовать некоторые основные компоненты.

• Назначьте тему комментарию QDoc — комментарий может быть страницей, документацией свойства, документацией класса или любой из доступных команд тем.
• Дайте теме контекст — QDoc может ассоциировать определенные темы с другими страницами, например, ассоциировать устаревшие функции, когда документация помечена командой \obsolete.
• Помечайте разделы документа с помощью команд разметки — QDoc может создавать макеты и форматировать документацию для документации.

В Qt класс QVector3D был задокументирован с помощью следующего комментария QDoc:

/*!
    \class QVector3D
    \brief The QVector3D class represents a vector or vertex in 3D space.
    \since 4.6
    \ingroup painting-3D

    Vectors are one of the main building blocks of 3D representation and
    drawing.  They consist of three coordinates, traditionally called
    x, y, and z.

    The QVector3D class can also be used to represent vertices in 3D space.
    We therefore do not need to provide a separate vertex class.

    \note By design values in the QVector3D instance are stored as \c float.
    This means that on platforms where the \c qreal arguments to QVector3D
    functions are represented by \c double values, it is possible to
    lose precision.

    \sa QVector2D, QVector4D, QQuaternion
*/

У него есть конструктор QVector3D::QVector3D(), который был задокументирован с помощью следующего комментария QDoc:

/*!
    \fn QVector3D::QVector3D(const QPoint& point)

    Constructs a vector with x and y coordinates from a 2D \a point, and a
    z coordinate of 0.
*/

Различные комментарии могут находиться в разных файлах, и QDoc соберет их в зависимости от их темы и контекста. Полученная документация из фрагментов генерируется в документацию класса QVector3D.

Обратите внимание, что если документация непосредственно предшествует функции или классу в исходном коде, то ей не требуется тема. QDoc предположит, что документация над кодом — это документация для этого кода.

Статья создается с помощью команды \page. Первый аргумент — HTML-файл, который создаст QDoc. Тема дополняется командами контекста, командами \title и \nextpage. Есть и другие команды QDoc, такие как команда \list.

/*!
    \page generic-guide.html
    \title Generic QDoc Guide
    \nextpage Creating QDoc Configuration Files
    There are three essential materials for generating documentation with QDoc:

    \list
        \li \c QDoc binary (\c {qdoc})
        \li \c qdocconf configuration files
        \li \c Documentation in \c C++, \c QML, and \c .qdoc files
    \endlist
*/

Раздел о командах тем предоставляет обзор нескольких других типов тем.