Как установить doxygen

gunzip doxygen-$VERSION.src.tar.gz # uncompress the archive tar xf doxygen-$VERSION.src.tar # unpack it

cd doxygen-$VERSION mkdir build cd build

cmake -G "Unix Makefiles" ..

cmake -Dbuild_wizard=YES ..

cmake -L ..

make

cmake -Dbuild_doc=YES .. make docs

cmake -DLIBCLANG_BUILD_STATIC=ON \ -DBUILD_SHARED_LIBS=OFF \ -DLLVM_ENABLE_PIC=OFF \ -DLLVM_BUILD_LLVM_DYLIB=OFF \ -DLLVM_BUILD_LLVM_C_DYLIB=OFF \ -DLLVM_ENABLE_TERMINFO=OFF \ path_to_llvm_root_source_dir

cmake -DCMAKE_BUILD_TYPE=Release \ "-DCMAKE_FIND_LIBRARY_SUFFIXES=.a" \ "-ldl;-lz;-lpthread" \ -Duse_libclang=YES \ path_to_doxygen_root_source_dir

make install

cd c:\tools tar zxvf doxygen-x.y.z.src.tar.gz

mkdir build cd build cmake -G "Visual Studio 14 2015" ..

mkdir build cd build cmake -G "NMake Makefiles" .. nmake

Go to the next section or return to the index.

• Generated on Sat Oct 21 2023 21:20:29 for Doxygen Manual by 1.10.0

Как установить doxygen

Автор: Malaja.
Дата написания: 28.04.2009.
Права на статью принадлежат автору и Клубу программистов «Весельчак У».

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

Сам Doxygen представляет собой инструмент для создания онлайн-документации к Вашему любимому и выстраданному коду. Он бесплатен, посему очень любим фирмами.

Инсталляция

Сначала загружаем сам doxygen, затем — графический инструмент graphviz, с помощью которого можно строить диаграммы:

• http://www.stack.nl/~dimitri/doxygen/
• http://www.graphviz.org/

Комментарии

Если мы хотим, чтобы в документации также появлялись наши комментарии, которые стоят в коде, их необходимо помечать таким образом:

/// сам комментарий
Остальные варианты — см. мануал.
Конфигурация
Теперь в нашей рабочей директории стартуем cmd, в котором набираем:
Соответственно, вместо мы пишем, что сами хотим (так, в моем примере это composTest_doxygen.cfg).

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

Если хотим увидеть список файлов, директорий и т.д.

Шаг 6. Смотреть дополнительное описание.

При включении опции GENERATE_TREEVIEW в документации появляется левая часть.

Рассмотрим последствия включения тех или иных тегов:
1. CALL_GRAPH и CALLER_GRAPH: создает схемы вызова функций:

2. COLLABORATION_GRAPH:

3. GRAPHICAL_HIERARCHY:

4. CLASS_DIAGRAMS и CLASS_GRAPH:

5. HAVE_DOT — должно быть включено для создания диаграмм.
6. HIDE_UNDOC_RELATIONS — лучше оставить выключенным.
7. DOT_IMAGE_FORMAT — попробовала установить jpg — не пошло. Оставила png.
8. DOT_PATH — указала место инсталляции графического инструмента.

9. MAX_DOT_GRAPH_DEPTH — в моем случае между установкой 0 или 50 разницы никакой. Но в каждом конкретном случае это надо смотреть самому.

Дополнительное описание

/*! \mainpage OMSp_MBT_ComposTest 
* 
* \section intro_sec Introduction 
* 
* Developer: 
* - имя 
* 
* \section requirements Requirements 
* The application OMSp_MBT_ComposTest.dll requires the following external stuff: 
* - lib1 
* - dll1 
* 
* \section changelog Changelog 
* 
* - February 2009: initial release 
* 
* \section About_sec About this documentation 
* 
* \subsection step1 Location 
* 
* This documentation can be found on file://dir1/dir2/index.html 
* 
* \subsection step2 Updating 
* 
* Requirements 
* - Installed doxygen package (from http://www.stack.nl/~dimitri/doxygen) 
* - Optional: Installed graphviz tool for diagrams (from http://www.graphviz.org) 
* 
Note: you have add the bin path of the installation to the 
* PATH environment variable 
* 
* Generating 
* 
* - go to source location dir1\project_dir  
* - open a cmd window 
* - type doxygen наш_конфиг_файл.cfg  
* 
* Configuration files 
* - наш_конфиг_файл.cfg  (text file; general configuration of input files and output) 
* - имя_этого_файла.txt (text file for processing this Main Page) 
*/

Документируем код эффективно при помощи Doxygen

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

1. Документируем код эффективно при помощи Doxygen
2. Оформление документации в Doxygen
3. Построение диаграмм и графов в Doxygen

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

Введение

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

Рассматриваемая система Doxygen как раз и выполняет эту задачу: она позволяет генерировать на основе исходного кода, содержащего комментарии специального вида, красивую и удобную документацию, содержащую в себе ссылки, диаграммы классов, вызовов и т.п. в различных форматах: HTML, LaTeX, CHM, RTF, PostScript, PDF, man-страницы.

1. Документация к API игрового движка CrystalSpace
2. Документация к Visualization Toolkit
3. Документация к исходникам Abiword
4. Документация к API KDE
5. Документация к API Drupal

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

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

Установка и настройка

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

Далее работа с Doxygen весьма тривиальна: достаточно запустить программу, указав ей путь к файлу с настройками.

doxygen

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

В принципе, для редактирования данного файла и, вообще, работой с Doxygen, можно воспользоваться программой Doxywizard, которая чаще всего идёт вместе с Doxygen и которая позволяет чуть удобнее работать с файлом настроек (слева – Doxywizard; справа – файл открытый в текстовом редакторе):

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

doxygen -g

Рассмотрим основные опции, которые могут вам пригодится, чтобы создать первую вашу документацию:

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

Для её генерации можно воспользоваться Doxywizard (для этого необходимо указать рабочую директорию, из которой будут браться исходные коды, перейти на вкладку «Run» и нажать «Run doxygen») или запустив программу Doxygen, указав ей в качестве параметра путь к файлу с настройками:

doxygen

Основы документирования на Doxygen

Теперь, когда мы разобрались с тем, как настраивать Doxygen и работать с ним, впору разобраться с тем, как необходимо документировать код, основными принципами и подходами.

1. Он может быть размещён перед или после объявления или определения класса, члена класса, функции, пространства имён и т.д.;
2. Либо его можно располагать в произвольном месте (и даже другом файле), но для этого потребуется явно указать в нём, к какому элементу кода он относится. Мы не будет рассматривать этот подход, поскольку даже разработчики рекомендуют его избегать, но если интересно, то подробнее о нём можно прочитать в документации.

Сразу отметим, что, вообще, всего существует два основных типа документирующих блоков: многострочный блок и однострочный блок.

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

Многострочный блок

Мы сказали, что любой блок – это комментарий, оформленный специальным образом. Поэтому необходимо определить каким таким «специальным образом». Вообще, существует целый ряд способов для описания многострочного блока, и выбор конкретного способа зависит от ваших предпочтений:

JavaDoc стиль (напоминает обычный C комментарий, но начинающийся с двух звездочек):

/** * . первая строчка . * . вторая строчка . */ 

При этом звездочки не обязательно ставить на каждой строке. Такая запись будет эквивалентной:

/** . первая строчка . . вторая строчка . */ 

/*! * . первая строчка . * . вторая строчка . */ 

Для указания краткого описания может быть использована команда \brief. Указанный после команды текст, вплоть до конца параграфа будет относится к краткому описания, и для отделения подробного описания и краткого описания используется пустая строка.

/*! \brief Краткое описание и его продолжение. Подробное описание */ 

Однострочный блок

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

Можно использовать специальный комментарий в C++ стиле:

/// Краткое описание 

//! Краткое описание 

Для указания подробного описания в однострочном документирующем блоке может быть использована команда \details:

/// \details Подробное описание 

Например следующие два способа документирования дадут один и тот же результат:

/// \brief Краткое описание /// \details Подробное описание 

///Краткое описание /*! Подробное описание */ 

Размещение документирующего блока после элемента

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

int variable; ///< Краткое описание 

Пример документации

Теперь рассмотрим то, как это будет выглядеть на практике. Ниже представлен документированный код некоторого класса в соответствии с теми правилами, которые мы рассматривали ранее.

/*! \brief Родительский класс, не несущий никакой смысловой нагрузки Данный класс имеет только одну простую цель: проиллюстрировать то, как Doxygen документирует наследование */ class Parent < public: Parent(); ~Parent(); >; 

В итоге Doxygen сформирует на основе данных комментариев следующую красиво оформленную страничку (здесь приведена вырезка из неё):

Теперь, когда мы научились основам, пришла пора познакомиться с тем, как можно детализировать документацию. Инструментом для этого являются команды.

Команды

С несколькими из команд в Doxygen мы успели познакомиться (речь идёт о \brief и \details), однако на самом деле их значительно больше. Полный их список приведён в официальной документации.

Вообще, любая команда в Doxygen представляет собой слово на английском языке предваренное символом "\" или "@" (обе записи тождественны) и таких команд очень много, порядка двухсот. Приведём для примера несколько таких команд:

Пример использования некоторых команд и результат приведены ниже:

/*! \brief Дочерний класс \author Norserium \version 1.0 \date Март 2015 года \warning Данный класс создан только в учебных целях Обычный дочерний класс, который отнаследован от ранее созданного класса Parent */ class Son : public Parent < public: Son(); ~Son(); >; 

Далее будут использоваться следующие обозначения при описании аргументов команды, когда будет приводиться её общий формат:

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

Документирование основных элементов исходного кода

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

Документирование файла

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

/*! \file \brief Заголовочный файл с описанием классов Данный файл содержит в себе определения основных классов, используемых в демонстрационной программе */ #ifndef CLASSES_H #define CLASSES_H . #endif // CLASSES_H 

Документирование функций и методов

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

Параметры

Для указания параметров необходимо использовать команду \param для каждого из параметров функции, при этом синтаксис команды имеет следующий вид:

\param []

1. Имя параметра – это имя, под которым данный параметр известен в документируемом коде;
2. Описание параметра представляет собой простое текстовое описание используемого параметра..
3. Направление – это опциональный атрибут, который показывает назначение параметра и может иметь три значения "[in]", "[out]", "[in,out]";

/*! Копирует содержимое из исходной области памяти в целевую область память \param[out] dest Целевая область памяти \param[in] src Исходная область памяти \param[in] n Количество байтов, которые необходимо скопировать */ void memcpy(void *dest, const void *src, size_t n); 

В результате мы получим такую вот аккуратную документацию функции:

Возвращаемое значение

Для описание возвращаемого значения используется команда \return (или её аналог \returns). Её синтаксис имеет следующий вид:

\return

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

/*! Находит сумму двух чисел \param a,b Складываемые числа \return Сумму двух чисел, переданных в качестве аргументов */ double sum(const double a, const double b); 

Получаем следующий результат:

Исключения

Для указания исключения используется команда \throw (или её синонимы: \throws, \exception), которая имеет следующий формат:

\throw

Простейший пример приведён ниже:

\throw std::bad_alloc В случае возникновения ошибки при выделении памяти 

Документирование классов

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

Если ваш язык не поддерживает явным образом определенные концепции, такие как например уровни доступа или создание методов, но их наличие подразумевается и его хотелось бы как-то выделить в документации, то существует ряд команд (например, \public, \private, \protected, \memberof), которые позволяют указать явно о них Doxygen.

Документирование перечислений

Документирование перечислений не сильно отличается от документирования других элементов. Рассмотрим пример, в котором иллюстрируется то, как можно удобно документировать их:

/// Набор возможных состояний объекта enum States < Disabled, ///< Указывает, что элемент недоступен для использования Undefined, ///< Указывает, что состояние элемента неопределенно Enabled, ///

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

Результат будет иметь следующий вид:

Модули

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

Далее мы кратко рассмотрим основные моменты и приведём пример, однако если вы хотите разобраться во всех тонкостях, то тогда придётся обратиться к соответствующему разделу документации.

Создание модуля

Для объявления модуля рекомендуется использовать команду \defgroup, которую необходимо заключить в документирующий блок:

\defgroup (заголовок модуля) 

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

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

/*! \defgroup maze_generation Генерация лабиринтов \brief Данный модуль, предназначен для генерации лабиринтов. На данный момент он поддерживает следующие алгоритмы генерации лабиринтов: Eller's algorithm, randomized Kruskal's algorithm, cellular automaton algorithm, randomized Prim's algorithm. */ 

Размещение документируемого элемента в модуле

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

Первый подход – это использование команды \ingroup:

\ingroup (заголовок модуля) 

Его недостатком является то, что данную команду надо добавлять в документирующие блоки каждого элемента исходного кода, поскольку их в рамках одного модуля может быть достаточно много.

Поэтому возникает необходимость в другом подходе, и второй подход состоит в использовании команд начала и конца группы: @ и @>. Следует отметить, что они используются наряду с командами \defgroup, \addtogroup и \weakgroup.

/*! \defgroup (заголовок модуля) @ < */ документируемые_элементы /*! @>*/ 

/*! \addtogroup [(заголовок модуля)] @ < */ документируемые_элементы /*! @>*/ 

/*! \defgroup main_module Главный модуль */ /*! \defgroup second_module Вложенный модуль \ingroup main_module */ 

/*! \defgroup generate_mazes Генерация лабиринтов \ingroup maze \brief Данный модуль, предназначен для генерации лабиринтов. На данный момент он поддерживает следующие алгоритмы генерации лабиринтов: Eller's algorithm, randomized Kruskal's algorithm, cellular automaton algorithm, randomized Prim's algorithm. */ ///@ < /*! \brief Функция генерации лабиринта на основе алгоритма Эллера \param width, height количество клеток в высоту и ширину в лабиринте \returns Лабиринт, представляющий собой экземпляр класса Maze с заданной шириной и высотой */ Maze generateEller(int width, int height); /*! \brief Функция генерации лабиринта на основе вероятностного алгоритма Крускала \param width, height количество клеток в высоту и ширину в лабиринте \returns Лабиринт, представляющий собой экземпляр класса Maze с заданной шириной и высотой */ Maze generateKruskal(int width, int height); /*! \brief Функция генерации лабиринта на основе вероятностного алгоритма Прима \param width, height количество клеток в высоту и ширину в лабиринте \returns Лабиринт, представляющий собой экземпляр класса Maze с заданной шириной и высотой */ Maze generatePrim(int width, int height); /*! \brief Функция генерации лабиринта на основе клеточных автоматов \param width, height количество клеток в высоту и ширину в лабиринте \returns Лабиринт, представляющий собой экземпляр класса Maze с заданной шириной и высотой */ Maze generateCellular(int width, int height); ///@>

/*! \defgroup maze Лабиринт \brief Основной модуль, содержащей в себе описания лабиринтов и содержащий другие модули для работы с ними */ ///@< class Maze < /* описание класса */ >; ///@> 

\code [ >] . \endcode 

/*! \brief Алгоритм Евклида \param a,b Два числа, чей наибольший делитель мы хотим найти Данная функция реализует алгоритм Евклида, при помощи которого находится наибольшее общее кратное у двух чисел. Код функции выглядит следующим образом: \code int gcd(int a, int b) < int r; while (b) < r = a % b; a = b; b = r; >return r; > \endcode */ int gcd(int a, int b); 

EXAMPLE_PATH = путь_к_директории 

\example

/*! \brief Алгоритм Евклида \param a,b Два числа, чей наибольший делитель мы хотим найти Данная функция реализует алгоритм Евклида, при помощи которого находится наибольшее общее кратное у двух чисел. */ int gcd(int a, int b); /*! \example main.cpp Пример того, как использовать функцию */ 

void main()

\include

\snippet ( имя_фрагмента ) 

/// [ имя_фрагмента ] . /// [ имя_фрагмента ] 

INLINE_SOURCES = YES 

USE_MATHJAX = YES 

 расстояние между \f$(x_1,y_1)\f$ и \f$(x_2,y_2)\f$ равно \f$\sqrt\f$. 

 \f[ |I_2|=\left| \int_^T \psi(t) \left\< u(a,t)- \int_<\gamma(t)>^a \frac \int_^\theta c(\xi)u_t(\xi,t)\,d\xi \right\> dt \right| \f] 

 \f< g &=& \frac \\ &=& \frac<(6.673 \times 10^<-11>\,\mbox^3\,\mbox^\, \mbox^)(5.9736 \times 10^\,\mbox)><(6371.01\,\mbox)^2> \\ &=& 9.82066032\,\mbox^2 \f> 

/*! \brief Вычисление факториала числа \f$ n \f$ \param n - число, чей факториал необходимо вычислить \return \f$ n! \f$ Данная функция вычисляет значение факториала числа \f$ n \f$, определяемое по формуле: \f[ n! = \prod_^n i \f] */ int factorial(int n); 

/*! Функция генерирующая псведослучайное число ------------------------------------------ Изначально планировалось реализовать в данной функции один из следующих методов генерации псевдослучайных чисел: - Линейный конгруэнтный метод; - Метод Фибоначчи; - Линейный регистр сдвига с обратной связью; - Вихрь Мерсенна. Но разработчики вспомнили про одну замечательную цитату: > Есть два способа создания дизайна программы. Один из них, это сделать его настолько простым, что в нем, очевидно, не будет недостатков. Другой способ — сделать его настолько запутанным, что в нем не будет очевидных недостатков. > — C.A. R. Hoare И выбрали первый путь. ![Описание функции](image.png) */ int getRandomNumber();