Небольшая заметка технического характера. Решил добавить к создаваемым примерам поддержку системы документирования Doxygen. С этой целью планирую добавлять в исходный код примеров специально оформленные комментарии, а в корневую папку проекта каждого примера пару специальных файлов:
- Doxyfile — файл с настройками для программы Doxygen.
- doxygen.bat — пакетный файл Windows, для быстрого запуска программы Doxygen с Doxyfile.
Для первого примера это уже сделано.
Библиотека STM32F4 DSP and standard peripherals library от STMicroelectronics, реализующая стандарт CMSIS и использующаяся при создании проектов в CoIDE, уже содержит код, со специально оформленными комментариями, на основе которых CoIDE и создаёт документацию. Поэтому, установив две указанные ниже программы, можно получать, на мой взгляд, достаточно приличную документацию на проект примера, с документированными функциями, структурами, константами, графами включаемых файлов, графами вызовов и исходными кодами, в которой при помощи мыши можно перемещаться по описаниям и определениям всех этих сущностей. Конечно, по большей части это повторяет ту документацию, которую можно посмотреть и в CoIDE, или ту, которую можно получить из html или chm документации, идущих вместе с STM32F4 DSP and standard peripherals library, и которую можно получить, скачав её по указанной ссылке, в разделе Get Software. Но с другой стороны, генерируемая документация будет именно документацией на рассматриваемые примеры, с включением в неё только тех компонентов, которые в конкретном примере используются. И настроить её можно в соответствии со своими пожеланиями, например, включив в неё дополнительные пояснения, рисунки, ссылки. Так же это можно рассматривать как тренировку в использовании Doxygen и навыков документирования кода.
Загружать получившуюся документацию в репозиторий я не стал. Для примера, рассматриваемого в прошлой заметке, её объём составил 21 Мб, что значительно превышает объём всего проекта, вместе с исходниками библиотек, и всеми получившимися в результате сборки файлами.
Чтобы сгенерировать документацию в формате html, нужно, чтобы были установлены следующие программы (ссылки даны на страницы загрузки):
Вы можете скачать для Doxygen испольняемый файл инсталлятора (на момент написания заметки doxygen-1.8.12-setup.exe), для Graphviz — файл инсталляционного пакета — msi (graphviz-2.38.msi). Можно так же скачать и zip архивы для обеих. Если скачали exe и msi — просто запускайте и двигайтесь вперёд по диалогам мастеров установки, отвечая на вопросы, если у Вас на то нет каких-то особых причин, можно не думая.
Установив программы, Вы можете обновить локальный репозиторий с файлами проекта из глобального: git pull. В корневой папке рассматриваемого прошлый раз примера stm32_base\gpio\leds_button\leds_button_c должны появиться файлы Doxyfile, doxygen.bat и папка doc. Запускаем doxygen.bat. Смотрим вывод в открывшейся консоли. Должны бежать сообщения, о выполняемых действиях.
Если Вы установили обе программы, но doxygen и/или утилита dot из пакета Graphviz при запуске doxygen.bat не находятся, возможно, при установке не прописались пути к их испольняемым файлам в переменной PATH окружения Windows. Graphviz я добавлял туда специально. О том как это сделать, можно почитать здесь. Там речь идёт о настройке переменной для выполнения кода java из коммандной строки, но рекомендации вполне подойдут и для перечисленных выше программ. Если Вы не меняли пути для установки по умолчанию, то у Вас в переменной PATH должны присутствовать следующие значения (версии могут отличаться):
C:\Program Files\doxygen\bin;C:\Program Files\Graphviz2.38\bin
После успешного запуска doxygen.bat в папке doc/html/ появится довольно много файлов. Находим и открываем index.html, и можно путешествовать по задействованным при сборке примера файлам.
При желании Вы можете настроить файл Doxyfile в соответствии со своими пожеланиями и получить документацию в других форматах.
Цикл из трёх статей о работе с Doxygen (ссылка на первую статью): Документируем код эффективно при помощи Doxygen
GPIO:Практика — Мигание светодиодами и обработка нажатия кнопки (C)