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

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

• Как сделать
• Учебник
• Обзор
• Статья
• ЧАВО (Часто задаваемые вопросы)
• Документация 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.

Пример UIComponents демонстрирует правильное использование команд QDoc для документирования типов QML и модулей QML.

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

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

readonly property int sampleReadOnlyProperty: 0

Например, в примере TabWidget есть вымышленное свойство только для чтения sampleReadOnlyProperty. Его объявление имеет идентификатор readonly и имеет начальное значение.

Свойства и сигналы, которые не предназначены для публичного интерфейса, могут быть помечены командой \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 также перечислит весь код примера.

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