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

Существует несколько типов предопределенных категорий или типов документации:

• Руководства по использованию
• Учебник
• Обзор
• Статья
• ЧАВО (Часто задаваемые вопросы)
• Документация API C++
• Документация типов QML
• Пример кода

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

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

QDoc отлично справляется с созданием документации API на основе набора исходного кода и документации в комментариях QDoc. В частности, QDoc учитывает архитектуру Qt и может проверить наличие документации для классов, функций или свойств Qt C++. QDoc выдает предупреждения и ошибки, если не может сопоставить документацию с элементом кода или если элемент кода не имеет документации.

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

QDoc будет анализировать заголовочные файлы (обычно .h файлы) для построения дерева структуры класса. Затем QDoc проанализирует исходные файлы и файлы документации, чтобы прикрепить документацию к структуре класса. После этого QDoc сгенерирует страницу для класса.

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

Стили языка

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

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

Документирование типов QML

В мире QML есть дополнительные сущности, которые необходимо документировать, такие как сигналы QML, присоединенные свойства и методы QML. Внутренне они используют технологии Qt, однако документация API QML требует другого макета и соглашений об именах по сравнению с документацией API Qt C++.

Список команд QDoc, относящихся к QML:

• \qmlattachedproperty
• \qmlattachedsignal
• \qmlbasictype
• \qmltype - создает документацию типа QML
• \qmlmethod
• \qmlproperty
• \qmlsignal
• \inherits
• \qmlmodule
• \inqmlmodule
• \instantiates

Примечание: Не забудьте включить разбор QML, добавив тип файла *.qml в переменную fileextension.

Для документирования типа QML начните с создания комментария QDoc, который использует команду \qmltype в качестве команды темы.

Парсер QML

Если ваш тип QML определен в файле qml, документируйте его там. Если ваш тип QML представлен классом C++, документируйте его в файле cpp для этого класса C++ и включите команду \instantiates, чтобы указать имя класса C++. Не документируйте тип QML в файле cpp, если тип QML определен в файле qml.

При документировании типа QML в файле qml размещайте каждый комментарий QDoc непосредственно над элементом, к которому относится комментарий. Например, поместите комментарий QDoc, содержащий команду \qmltype (комментарий темы), непосредственно над внешним типом QML в файле qml. Поместите комментарий для документирования свойства QML непосредственно над объявлением свойства, и так далее для обработчиков сигналов QML и методов QML. Обратите внимание, что при документировании свойств QML в файле qml обычно не включают команду \qmlproperty в качестве команды темы (которую необходимо использовать при документировании типов QML в файлах cpp), поскольку парсер QML автоматически сопоставляет каждый комментарий QDoc со следующим объявлением QML, которое он анализирует. То же самое относится к комментариям обработчиков сигналов QML и методов QML. Однако иногда полезно включить одну или несколько команд \qmlproperty в комментарий, например, когда тип свойства — другой тип QML и вы хотите, чтобы пользователь использовал только определенные свойства в этом другом типе QML, а не все. Но при документировании свойства, имеющего псевдоним, поместите комментарий QDoc для него непосредственно над объявлением псевдонима. В этих случаях комментарий QDoc *должен* содержать команду \qmlproperty, поскольку это единственный способ, которым QDoc может узнать тип свойства с псевдонимом.

При документировании типа QML в файле cpp соответствующего класса C++ (если он есть), обычно помещайте каждый комментарий QDoc непосредственно над элементом, который он документирует. Однако QDoc не использует парсер QML для анализа этих файлов (используется парсер C++), поэтому эти комментарии QML QDoc могут появляться где угодно в файле cpp. Обратите внимание, что комментарии QML QDoc в файлах cpp *обязательно* должны использовать команды темы QML. Т. е. команда \qmltype *обязательно* должна присутствовать в комментарии QDoc для типа QML, а команда \qmlproperty *обязательно* должна присутствовать в каждом комментарии QML для свойства.

Модули QML

Тип QML принадлежит модулю. Модуль может включать все связанные типы для платформы или содержать определенную версию Qt Quick. Например, типы QML Qt Quick 2 принадлежат модулю Qt Quick 2, в то время как также есть модуль Qt Quick 1 для более старых типов, представленных в Qt 4.

Модули QML позволяют группировать типы QML. Команда темы \qmltype должна иметь контекстную команду \inqmlmodule для связи типа с модулем QML. Аналогично, команда темы \qmlmodule должна существовать в отдельном файле .qdoc для создания страницы обзора модуля. На странице обзора будут перечислены типы QML модуля QML.

Ссылки на типы QML должны также содержать имя модуля. Например, если тип под названием TabWidget находится в модуле UIComponents, он должен быть связан как UIComponents::TabWidget.

Только для чтения и внутренние свойства QML

QDoc обнаруживает свойства QML, которые помечены как readonly. Обратите внимание, что свойство должно быть инициализировано значением.

readonly property int sampleReadOnlyProperty: 0

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

Статьи и обзоры

Статьи и обзоры — это стиль написания, который лучше всего подходит для предоставления сводной информации по теме или концепции. Это может ввести новую технологию или обсудить, как может быть применена концепция, но без слишком подробного обсуждения точных шагов. Однако такой контент может служить точкой входа для читателей для поиска учебных и справочных материалов, таких как учебники, примеры и документация классов. Примером обзора может быть страница продукта, например, общее обсуждение Qt Quick, отдельных модулей, принципов проектирования или инструментов.

Чтобы указать, что документ является статьей, добавьте ключевое слово article к команде \page:

/*!
    \page overview-qt-technology.html overview
    \title Overview of a Qt Technology

    \brief provides a technology never seen before.

*/

В разделе команд темы написания приведен список доступных аргументов команды \page.

Учебники, руководства по использованию, Часто задаваемые вопросы

Учебники, руководства по использованию и Часто задаваемые вопросы (ЧАВО) — это все учебные материалы, которые обучают или дают указания читателю. Учебники — это контент, предназначенный для сопровождения читателя по прогрессивному пути обучения концепции или технологии. Руководства по использованию и Часто задаваемые вопросы (ЧАВО) предоставляют руководство, представляя материал в виде ответов на часто задаваемые вопросы. Руководства по использованию и Часто задаваемые вопросы (ЧАВО) предназначены для удобного доступа и не обязательно представляются в линейной последовательности.

Для создания этих типов помечайте страницы, указав аргумент type для команды \page. Аргумент type — это второй аргумент, а имя файла — первый.

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

    \brief All the questions about altruism, answered.

    ...
*/

В разделе команд темы написания приведен список доступных аргументов команды \page.

Примеры кода

Примеры — это эффективный способ продемонстрировать практическое применение определенной технологии или концепции. В случае с программным обеспечением это обычно представлено в виде приложения с простым кодом и четкими объяснениями того, что делает код. Любой модуль, API, проект, шаблон и т. д. должен иметь, по крайней мере, один хороший пример.

Пример может сопровождаться учебником. Учебник дает инструкции и описание кода, а пример кода — это содержимое кода, которое пользователи могут изучить. К примерам кода могут прилагаться тексты, которые отсутствуют в учебнике.

QDoc создаст страницу, содержащую пример кода с описанием, используя команду \example.

/*!
    \title UI Components: Tab Widget Example
    \example declarative/ui-components/tabwidget

    This example shows how to create a tab widget. It also demonstrates how
    \l {Property aliases}{property aliases} and
    \l {Introduction to the QML Language#Default Properties}{default properties} can be used to collect and
    assemble the child items declared within an \l Item.

    \image qml-tabwidget-example.png
*/

QDoc будет использовать каталог, указанный в переменной ввода exampledirs, для поиска файла проекта Qt (.pro) для генерации файлов примера. Сгенерированный HTML будет иметь имя файла declarative-ui-components-tabwidget.html. QDoc также отобразит весь пример кода.

Примечание: Файл проекта примера должен совпадать с именем каталога.