Довольно часто возникает необходимость разобрать новый большой проект и не совсем очевидно с какой стороны подступиться к огромной горе исходных кодов которая свалилась на вас. Если вам повезло и проект написан на C++, C, Objective-C, Python, Java, PHP, C#, Фортран или VHDL то простое решение есть – Doxygen + GraphWiz.

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

В качестве примера я решил взять LLVM с размером исходного кода около 12Мб. На построение документации ушло около 2 минут, что, конечно, не мало, но с учетом однократности подобной операции совершенно не критично.

Разбор исходников

Основная цель Doxygen – создать документацию к проекту, для чего используются комментарии в специальном формате. Очевидно что такой информации не достаточно для изучения нового проекта и хочется большего. Например, включения не только функций снабженных коментариями, но и всех остальных функций включая private и static функции, которые по умолчанию в документацию не попадают. За то, какие функции участвуют в построении документации отвечают следующие флаги: EXTRACT_ALL, EXTRACT_PRIVATE, EXTRACT_STATIC, EXTRACT_PACKAGE, MACRO_EXPANSION. Для того что бы сделать тот или иной флаг активным, ему нужно присвоить значение YES.

Отображение исходного кода

Крайне полезная возможность Doxygen – включение исходных кодов с гиперссылками на соответствующие классы/методы/переменные. Включение исходного кода в документацию управляется по средствам флагов: SOURCE_BROWSER, REFERENCED_BY_RELATION, REFERENCES_RELATION. Результат получается очень практичным и может выглядеть, например, так:

Диаграммы

Но ведь код можно посмотреть и с любимой IDE! Поэтому следующий шаг – диараммы. Диаграммы классов, диаграммы зависимостей между заголовками, диаграммы зависимостей между модулями, прямые и обратные диаграммы вызовов. За все это разнообразие диаграмм отвечает GraphWiz: CLASS_DIAGRAMS, CALL_GRAPH, CALLER_GRAPH, HAVE_DOT, DOT_PATH. С его параметрами все так же как и раньше, достаточно задать YES для всего кроме DOT_PATH, куда передается путь к исполнимому модулю GraphWiz.

А на выходе…

Кстати, на этом подготовительный этап заканчивается и можно запускать генерацию документации. На выходе должно получиться следующее.
Зависимости между заголовочными файлами с возможностью навигации.

Каждая функция снабжается информацией о том, что вызывается из нее и откуда ее вызывают.

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

Откуда вызывается функция.

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

Удачных исследований!