Построение диаграмм и графов в Doxygen

Данная статья входит в получившийся цикл статей о системе документирования Doxygen:

Doxygen позволяет автоматически строить на основе исходного кода достаточно большое количество разнообразных диаграмм и графов, призванных проиллюстрировать те или иные элементы исходного кода, при этом любой график может служить также и способом навигации по коду и документации, поскольку Doxygen автоматически проставляет поверх самого графика ссылки на соответствующие разделы документации. В живую на результат его работы можно посмотреть, например, здесь и здесь (в последнем примере они для компактности свернуты).

• Диаграмма наследования классов
• Диаграмма кооперации классов
• Диаграмма иерархии классов
• Граф вызовов
• Граф вызывающих функций
• Граф зависимостей (прямых и обратных)

По умолчанию возможности Doxygen для построения различного рода диаграмм и графов очень ограничены (доступна только диаграмма наследования классов), пример такой диаграммы приведён ниже:

Для того, чтобы строить более продвинутые диаграммы и графы потребуется Graphviz, специальное открытое программное обеспечение, предназначенное для построения различного рода графов. Скачать его можно здесь.

После его установки необходимо выполнить некоторые изменения в файле настроек Doxygen. Для этого используются следующие команды:

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

Диаграмма наследования классов (class graph) предназначена для графического отображения отношений наследования между классами (как «вверх», так и «вниз»).

Для того, чтобы сгенерировать такую диаграмму для всех документированных классов (при этом если в файле настроек установлена, например, опция EXTRACT_ALL, то к документированным классам относятся все классы) необходимо установить следующую опцию в файле настроек:

Ниже приведён пример построения такой диаграммы для тестового примера (он взят из легенды, создаваемой Doxygen), иллюстрирующего различные виды отношений между классами:

Исходный код примера:

Диаграмма кооперации классов (collaboration graph) предназначена для графического отображения отношений наследования между классами (только «вверх», то есть показаны будут только родительские классы), а также взаимодействие между ними, под которым в данном случае понимается то, что один класс содержит среди атрибутов объект другого класса.

Для того, чтобы включить диаграмму наследования классов, необходимо установить команду COLLABORATION_GRAPH:

Ниже представлена диаграмма кооперации классов для того же примера, который был рассмотрен ранее:

Следует отметить, что в данном случае отличие от диаграммы наследования классов состоит только в том, что здесь отображена связь между классами Inherited и Used, которая выражается в том, что первый класс имеет атрибут, являющийся экземпляром второго класса. Обозначение для такой связи следующее:

Всё остальное, сказанное ранее про настройки диаграммы наследования классов остаётся справедливым и здесь.

Диаграмма иерархии классов (graphical hierarchy) предназначена только для отображения отношений наследования между множеством разных классов. Фактически, она представляет собой графическое представление текстового описания иерархии классов, которое генерируется по умолчанию:

Прежде, чем перейти к описанию данного типа графов, договоримся, что всё сказанное далее справедливо и для функций и для методов классов, но для краткости мы будем употреблять слово «функции». Итак, граф вызовов (call graph), иллюстрирует то, какие функции вызываются внутри тела документируемой функции, а также во всех вложенных функциях (глубину можно настраивать, задавая максимальную глубину графа в файле настроек).

Для того, чтобы построить граф вызовов функции могут быть использованы два подхода: установка опции, которая вызовет построение графов вызовов для всех функций, и использование специальной команды, которая добавляется в описании функции (последнее может оказаться предпочтительнее, если вам надо проиллюстрировать конкретную функцию или ваш проект очень большой).

Для первого подхода необходимо установить следующую опцию:

Для второго подхода используется следующая команда:

Пример графа вызова изображен ниже. Формулы на изображении ниже даны для примера (функция combination вычисляет число сочетаний, а для вычисления факториала использует формулу Стирлинга):

Граф вызывающих функций (caller graph), иллюстрирует цепочку вызовов различных функций в результате которого вызывается документируемая функция, (глубина такой цепочки может быть настроена путём настройки максимальной глубины графа в файле настроек).

Опять же есть два способа построения таких графов. Первый способ – это установка соответствующей опции в файле настроек:

Второй способ – это использование специальной команды:

Простой пример графа вызывающих функций приведён ниже:

Кратко поясним его: для вычисления факториала по формуле Стирлинга используется функция возведения в степень (pow), для вычисления экспоненты также используется данная функция, а вычисление экспоненты может быть использовано для вычисления значений гиперболических функций.

Граф зависимостей идейно близок к графу вызовов, только он иллюстрирует не вызовы, а зависимости между различными файлами исходного кода.

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

Для построения такого рода графов необходимо установить следующую опцию в файле настроек:

Пример приведён ниже:

Обратный граф зависимостей (included by graph) иллюстрирует цепочку зависимостей от документируемого файла, т.е. то какие файлы включают в себя документируемый файл, затем в какие файлы включены данные файлы и т.д.

Для построения такого рода графов необходимо установить следующую опцию в файле настроек:

Пример приведён ниже:

Граф директорий (directory graph) предназначен для графического представления рассматриваемой директории. Для построения такого графа используется следующая опция:

Обратите внимание на то, что один из элементов графа имеет красную обводку, это означает, что в данную директорию вложены другие директории.

Doxygen позволяет создавать диаграммы «в стиле, схожем с Unified Modeling Language». Разработчики очень аккуратно выражаются в этом плане, поскольку эта возможность не подразумевает то, что на основе кода будет построена аккауратная и грамотная UML-схема, для этой задачи следует использовать другие инструменты, да и они зачастую дают сбои, поскольку в UML в первую очередь выражается идея, пусть и порой достаточно близкая к конкретной реализации.

Итак, для того чтобы строить диаграммы в UML стиле, необходимо установить следующую опцию:

Вновь обратимся к используемому ранее примеру, только дополним его открытыми, закрытыми и защищенными атрибутами и методами:

К сожалению, Doxygen зачастую не в состоянии отразить многие более сложные концепции, хотя бы просто потому, что нельзя указать, какие конкретно классы необходимо включить в диаграмму. Поэтому в тех случаях, когда необходимо проиллюстрировать, например, примененный шаблон проектирования или какое-то иное решение, иногда проще и эффективнее построить схему в ином редакторе и просто импортировать её. Благо, что для одного из очень распространенных специализированных редакторов PlantUML у Doxygen есть встроенная поддержка (для его использования необходимо указать путь к в опции ).

В первую очередь необходимо убедится в том, что Java установлена на вашем компьютере и корректно настроена и затем указать корректный путь к jar файлу при помощи соответствующей опции:

После этого для вставки диаграммы PlantUML необходимо использовать соответствующие команды \startuml и \enduml:

Все параметры в данном случае необязательны. Параметр file указывает имя для сгенерированного файла, если его не указать, то оно будет выбрано автоматически; параметр caption устанавливает подпись к схеме; последний параметр используется для указания размера схемы.

Теперь перейдём непосредственно к примеру (далее изображена диаграмма для шаблона проектирования «компоновщик»):

Результат представлен ниже:

Наконец, следует отметить, что схемы можно строить в любом предпочитаемым вами редакторе или при помощи других генераторов, а затем результат импортировать в Doxygen. Вообще, всё зависит от ваших требований и тех задач, которые стоят перед вами; в некоторых случаях тех возможностей, которые предоставляет вам Doxygen, хватит с головой, и тогда я, надеюсь, эта статья окажется для вас приятной находкой; а иногда их может оказаться недостаточно и тогда потребуется применение других инструментов и других решений.