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

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

927

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

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

Основными типами диаграмм и графов, которые можно выстроить с его помощью, являются:

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

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

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

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

Опосля его установки нужно выполнить некие конфигурации в файле опций Doxygen. Для этого употребляются последующие команды:
Команда
Назначение
HAVE_DOT
Указывает, что для генерации диаграмм и графов нужно применять Graphviz (по умолчанию отключена)
DOT_PATH
Показывает путь к исполняемому файлу «dot.exe» (по умолчанию предполагается, что путь к нему имеется в переменной path; как правило, так оно и есть).
Посреди доп опций, которые могут понадобиться в предстоящем, можно отметить последующие:
Команда
Назначение
DOT_GRAPH_MAX_NODES
Раз число узлов станет больше установленного значения, то граф будет урезан, в итоге чего же родительский узел, чьи дочерние узлы были укрыты, станет выделен красноватым (раз же число узлов было задано меньше, чем число малышей корневого узла, то он совсем не будет показан) Устанавливает наибольшее количество узлов, которые будут отображаться в графе.
MAX_DOT_GRAPH_DEPTH
Устанавливает наивысшую глубину графа (глубина равна число граней от более удаленного узла графа до корневого узла). Снова же, раз глубина графа будет превосходить это значение, то он будет обрезан, в итоге чего же родительский узел, чьи дочерние узлы были укрыты, станет выделен красноватым
DOT_IMAGE_FORMAT
Показывает формат, в котором будут создаваться диаграммы и графы (поддерживаются «png», «jpg», «svg», «gif»)
DOT_FONTNAME
Устанавливает гарнитуру используемую для отображения текста на графах и диаграммах
DOT_FONTSIZE
Показывает кегль (высота букв, измеряемая в пт) для текста на графах и диаграммах
DOT_FONTPATH
Показывает путь к папке со шрифтовыми файлами
HTML_DYNAMIC_SECTIONS
В случае установки данной функции, Doxygen будет сворачивать определенные элементы HTML документации (к примеру, графы), которые юзер по желанию может потом раскрыть
Итак, сейчас когда мы разобрались с основными опциями, мы готовы приступить к конкретно главным типам диаграмм и графиков.

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

Для того, чтоб сгенерировать такую диаграмму для всех документированных классов (при этом раз в файле опций установлена, к примеру, функция EXTRACT_ALL, то к документированным классам относятся все классы) нужно установить последующую опцию в файле опций:
CLASS_GRAPH = YES
Ниже приведён пример построения таковой диаграммы для тестового примера (он взят из легенды, создаваемой Doxygen), иллюстрирующего разные виды отношений меж классами:

Начальный код примера и используемые настройкиИзмененные опции:
CLASS_GRAPH = YES
MAX_DOT_GRAPH_DEPTH = 2
TEMPLATE_RELATIONS = YES
Начальный код примера:
Class that is used by the Inherited class */
class Used { };

/*! /*! Class that is inherited using public inheritance */
class PublicBase : public Truncated { };

/*! Truncated class, inheritance relation is hidden */
class Truncated : public Invisible { };

/*! Super class that inherits a number of other classes */
class Inherited : public PublicBase,
protected ProtectedBase,
private PrivateBase,
public Undocumented,
public Templ<int>
{
public:
Used *m_usedClass;
}; Class that is inherited using protected inheritance */
class ProtectedBase { };

/*! Class that is inherited using private inheritance */
class PrivateBase { };

/*! Invisible class because of truncation */
class Invisible { };

/*! A template class */
template<class T> class Templ { };

/*!

Сейчас разглядим, что означают те либо другие условные обозначения.

Корневой узел

Обыденный узел, соответственный документированному классу

Узел, соответственный недокументированному классу

Родительский узел, чьи дочерние узлы были укрыты (к примеру, в силу ограничения на число узлов в графе либо его глубину)

Показывает на открытое наследование

Показывает на защищенное наследование

Показывает на закрытое наследование

Показывает, что класс является специализацией некого шаблонного класса, при этом подпись рядом со стрелкой показывает на то, какой шаблонный параметр был указан при специализации
Следует направить внимание на последующие функции:
Функция
Значение
По умолчанию
HIDE_UNDOC_RELATIONS
Указывает, нужно ли скрывать связь с неким классом, раз он недокументирован либо не является классом
YES
TEMPLATE_RELATIONS
Устанавливает, нужно ли показывать связь, показывающую, что один класс является специализацией другого
NO

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

Для того, чтоб включить диаграмму наследования классов, нужно установить команду COLLABORATION_GRAPH:
COLLABORATION_GRAPH = YES
Ниже представлена диаграмма кооперации классов для того же примера, который был рассмотрен ранее:

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

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

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

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

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

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

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

1-ый метод – это установка соответственной функции в файле опций: Снова же есть два метода построения таковых графов.
CALLER_GRAPH = YES
2-ой метод – это внедрение специальной команды:
callergraph
Обычный пример графа вызывающих функций приведён ниже:

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

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

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

Для построения такового рода графов нужно установить последующую опцию в файле опций:
INCLUDE_GRAPH = YES
Пример приведён ниже:

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

Для построения такового рода графов нужно установить последующую опцию в файле опций:
INCLUDED_BY_GRAPH = YES
Пример приведён ниже:

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

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

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

Итак для того, чтоб строить диаграммы в UML стиле нужно установить последующую опцию:
UML_LOOK = YES
Вновь обратимся к используемому ранее примеру, лишь дополним его открытыми, закрытыми и защищенными аттрибутами и способами:

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

В первую очередь нужно удостоверится в том, что Java установлена на вашем компе и корректно настроена и потом указать корректный путь к jar файлу при помощи соответственной функции:
PLANTUML_JAR_PATH = путь_к_jar_файлу
Опосля этого для вставки диаграммы PlantUML нужно применять надлежащие команды startuml и enduml:
enduml startuml [{file}] ["caption"] [<sizeindication>=<size>]

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

Сейчас перейдём конкретно к примеру (дальше изображена диаграмма для шаблона проектирования «компоновщик»):
Composite pattern) — структурный шаблон проектирования, объединяющий объекты в древовидную структуру для представления иерархии от личного к целому. Ниже представлена иллюстрация данного шаблона при помощи UML:
startuml
interface Component {
+doThis()
}
class Composite {
-elements
+addElement()
+doThis()
}
class Leaf {
+doThis()
}
Component <|— Leaf
Component<|— Composite
Composite o— Component
enduml
*/ Компоновщик дозволяет клиентам обращаться к отдельным объектам и к группам объектов идиентично. /*! file
Компоновщик (англ.
Итог представлен ниже:

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

Спасибо за внимание! habrahabr.ru