Батут с некоторыми операторами using.

Iceoryx-концы, такие как Publisher, Subscriber и т. д., являются примерами, где публичный заголовок включает только оператор using для фактической реализации.

Чтобы включить документацию этих компонентов, заголовок, содержащий документацию, можно добавить в список INCLUDE_DIR_AND_ADDITIONAL_FILES в файле CMakeLists.txt.

Генерация Doxygen

Для генерации документации из кода используется CMake в сочетании с Doxygen. В iceoryx_meta определён флаг сборки BUILD_DOC, который генерирует для вас HTML, XML и LaTeX-документацию. Нет необходимости предварительно собирать Iceoryx.

cmake -Bbuild -Hiceoryx_meta -DBUILD_DOC=ON
cmake --build build

Вывод хранится в папке build/doc/<iceoryx_component>, где вы можете найти папки html, xml и latex. Если вы хотите создать PDF-файлы, вы можете использовать tools/iceoryx_build_test.sh:

./tools/iceoryx_build_test.sh doc

Сгенерированные PDF-файлы создаются в папке build/doc. Обратите внимание, что Iceoryx не собирается.

Как правило, вы не найдёте никаких файлов Doxygen в нашем репозитории, потому что мы позволяем CMake генерировать их. В CMakeLists.txt есть команда doxygen_add_docs, которая выполняет эту работу. Там же мы устанавливаем некоторые параметры и псевдонимы для пользовательских тегов. Псевдонимы с xrefitem создают страницу, на которой собраны все вхождения соответствующего тега.

Заголовок файла

Пожалуйста, смотрите Header (CONTRIBUTING.md#header).

Включить защиту

Каждый заголовок и файл inl должен иметь защиту включения. Pragma once не допускается. Защита включения помещается непосредственно под заголовком файла и должна иметь следующую схему:

• IOX_[COMPONENT_W/O_ICEORYX][SUB_COMPONENT][FILE_NAME]
• IOX_[COMPONENT_W/O_ICEORYX][SUB_COMPONEN][SUB_COMPONENT]_[FILE_NAME]

См. файлы заголовков в iceoryx/doc/aspice_swe3_4/example.

PlantUML

Если вы хотите сделать видимыми сложные аспекты вашей реализации, вы можете написать PlantUML непосредственно в описании Doxygen вашего класса. Пример можно найти в example_base_class.hpp (example/iceoryx_component/source/example_module/example_base_class.hpp).

Наличие установленного PlantUML не обязательно. Если вы хотите его использовать, вам необходимо установить его, и переменная PLANTUML_JAR_PATH должна быть установлена. CMake попытается найти plantuml.jar в /usr/share/plantuml, если он не найден, то он попытается использовать переменную среды. Вы можете установить её, вызвав:

export PLANTUML_JAR_PATH=/custom/path

Хорошие примеры использования PlantUML можно найти на сайте https://plantuml.com.

Pull-Request

В Iceoryx Pull-Requests — это PDF-файлы, сгенерированные и загруженные в хранилище артефактов Github.

Если вы хотите загрузить PDF-файлы из Pull-запросов или основной сборки, вы можете сделать это следующим образом:

• Откройте представление «Проверки» в PR.
• Откройте ссылку «Подробности» для проверки iceoryx-coverage-doxygen-ubuntu в разделе «Покрытие тестами + документация Doxygen».
• На правой стороне вы найдёте кнопку меню «Артефакты», которая показывает iceoryx-pdf в качестве ссылки для скачивания.