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

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

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

Примеры кода

Примеры — эффективный способ продемонстрировать практическое использование конкретной технологии или концепции. В случае с middleware это обычно приложение, использующее простой код и чёткие объяснения того, что делает код. Любой модуль, 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 Project (.pro) для генерации файлов примера. Сгенерированный HTML будет иметь имя файла declarative-ui-components-tabwidget.html. QDoc также перечислит весь пример кода.

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