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

Обновлено: 03.07.2024

Большинство Java программистов знакомы с автоматическим созданием документации, которая может быть создана при помощи программы JavaDocs. Идея заключается в структурированном комментировании кода и создании удобного файла справки.

В мире C++ также есть несколько автоматических генераторов документации, одними из лидеров являются программы Microsoft's SandCastle и Doxygen.

Я решил проверить, насколько хорошо Doxygen сможет документировать MQL5, который, по сути, является подмножеством C++. На мой взгляд, поддержка объектно-ориентированного программирования - это важный шаг в зрелости MQL5, поскольку теперь язык позволяет создавать большие библиотеки классов. Этот эксперимент удался, и я надеюсь, что документация, создаваемая программой Doxygen из MQL5-кода, будет очень полезна.

2. Программа Doxygen

Программа Doxygen является системой автоматического создания документации c открытым исходным кодом в соответствии с GNU General Public License. Это означает, что ее разработка была похожа на другие проекты с открытым кодом, такие как Linux и Mozilla. Ее можно бесплатно скачать и использовать, исходный код Doxygen открыт для всех. Программа была разработана и совершенствуется несколькими разработчиками.

При обычном создании документации Doxygen просто разбирает весь C++ (или MQL5) код в проекте и отображает его структуру в файле справки, удобном для навигации. Это особенно полезно для объектно-ориентированных программ, которые, как правило, имеют обширные классовые иерархии и большое количество функций - членов классов. Для полного использования возможностей Doxygen, комментарии в коде также должны быть структурированы, чтобы Doxygen смог их интерпретировать и добавить информацию в генерируемый файл справки.

2.1 Загружаем Doxygen

Рис 1. Загрузка Doxygen

2.2 Настраиваем и запускаем Doxygen

Для настройки Doxygen нужно сделать небольшие настройки - добавить типы файлов *.mqh и *.mq5 и включить генерацию справки HTML. Следующие пять картинок подробно описывают процесс настройки.

Первые четыре скриншота (рис 2-5) - настройки опций вкладки "Wizard":

Рис 2. Настройка Doxygen - Wizard 1

Рис 3. Настройка Doxygen - Wizard 2

Рис 4. Настройка Doxygen - Wizard 3

Рис 5. Настройка Doxygen - Wizard 4

И наконец, в опциях "Expert" в описании входных файлов нужно добавить файлы с расширениями .mqh и .mq5:

Рис. 6. Настройка Doxygen - добавляем типы файлов mqh и mq5

Теперь все готово. Имейте в виду, что Doxgyen сохранит данные настройки в конфигурационном файле. Подготовленный файл с настройками приложен к статье.

Рис 7. Запуск Doxygen

2.3 Использование Doxygen

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

В качестве примера рассмотрим функцию CiMACD::Create() в файле MQL5/Include/Oscilators.mqh. Имейте ввиду, что файлы с описанием индикаторов отсутствуют в самой первой поставке MetaTrader 5. Для их получения, возможно, понадобится скачать последнюю версию MetaTrader 5.

Некоторые простые изменения ключевых слов позволят программе Doxygen правильно интрепретировать комментарии.

Для этого комментарии должны быть вида "///" (вместо "//"), в описании входных параметров "INPUT:" нужно заменить на "\param", а "OUTPUT:" на "\return".

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

Рис 8. Описание функции CiMACD::Create(), созданное Doxygen

2.4 Используем Doxygen для документирования всего кода, поставляемого с MQL5

Сила Doxygen - в создании файлов справки для больших проектов. Состав поставки MetaTrader 5 (каталог MQL5) содержит более сотни файлов .mq5 и .mqh, многие из которых взаимосвязаны.

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

Для создания справки по всему коду MQL5, поставляемому с MetaTrader, нужно сделать следующее:

Скопировать содержимое каталога MQL5 вместе подкаталогами в каталог MQL5/files.
Удалить файл MQL5/files/MQL5/Include/Strings/string.mqh - по неизвестной причине Doxygen не может его правильно интерпретировать.

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

Из каталога MQL5/Files запустить комманду "xcopy *.mq* c:\ /S/L > MQL5codeList.txt"
Запустить скрипт MetaquotesCommentsToDoxygen.mq5 на любом графике.

Полученная в результате документация имеет хорошее качество и быстро демонстрирует свою пользу - примеры приведены на рис 9-12.

Рис 9. Список классов, созданный Doxygen

Рис 10. Диаграмма потомков класса CArrayObj, созданная Doxygen

Рис. 11. Список функций класса CArrayObj, созданный Doxygen

Рис 12. Список определений (defines), созданные Doxygen

3. Программа Microsoft HTML Help Workshop

Остался всего один шаг для того, чтобы сделать еще более удобной документацию, созданную при помощи Doxygen. Программа Doxygen создает файл index.html, который содержит ссылки на множество других html-файлов и картинок. Это похоже на небольшой web-сайт, такая громоздкость делает документацию неудобной для распространения.

Давным-давно Microsoft осознала, что файлы справки для Windows-приложений лучше делать в HTML, для этой цели они разработали программу HTML Help Workshop. Эта программа берет файлы, созданные при помощи Doxygen, и компилирует их в один файл справки CHM. Файлы справки MetaTrader 5/MQL5 имеют тот же формат.

3.1 Загружаем HTML Help Workshop

Вы можете скачать и установить htmlhelp.exe с сайта Microsoft.

Рис 13. Загрузка HTML Help Workshop

3.2 Создаем скомпилированный файл справки HTML

Результаты работы Doxygen могут быть легко сконвертированы в файл справки CHM при помощи программы HTML Help Workshop. Используя наши настройки, Doxygen создает файл index.hhp, готовый для использования в программе HTML Help Workshop, как показано на рис. 14.

Рис 14. Местонахождение файлов index.htm и index.hhp, созданных Doxygen

Следующий шаг - компиляция:

Рис 15. Компиляция файлов в CHM при помощи HTML Help Workshop

4. Итоги

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

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

Содержание

Введение

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

На сегодняшний день существует огромное количество программного кода разной тематики, который доступен под разными лицензиями в сети и может заметно облегчить жизнь программиста, начинающего работу с задачами, связанными с ГИС.

Рассмотрим пример: допустим возник вопрос написания ПО для векторизации специфичного типа карт, среди прочего понадобится иметь на руках код, который должен осуществлять привязку карты. В сфере ГИС существует несколько открытых проектов, где эта задача уже решена, например GRASS. GRASS распространяется под лицензией GPL и каждый желающий может изучить его исходный код и, при желании, использовать их в своем программном обеспечении в соответствии с условиями лицензии (внимательно ознакомтесь с ней, прежде чем использовать данный код).

Устанавливаем Doxygen

GRASS изначально создавался для Unix платформ и его компиляция для Windows непростая задача (про установку GRASS). Изучив описание, убедимся, что в программе присутствует необходимый код. Скачав исходники легко обнаружить, что их объём составляет более 560 тыс. строк что заставляет задуматься о более эффективном их изучении.

Скачаем и установим Doxygen для Windows, имеющий графический интерфейс пользователя.

Разбор кода

Воспользуемся для начала работы Помощником (Wizard).

Значение параметров на вкладке «Project» вопросов вызвать не должно, заполним ее в соответствии со иллюстрацией и, переходим на вкладку «Mode». Здесь мы говорим программе обрабатывать весь код и указываем язык, на котором написан наш проект (GRASS написан на С).

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

Здесь, опять же, на ваше усмотрение.

Нажимаем «OK» и сохраняем проект:

В «Step 3» нужно указать папку, откуда должен быть загружен Doxygen (например C:\Program Files\doxygen\bin\)

Затем переходим к четвертому шагу и нажимаем «Start». Процесс обработки достаточно длительный и может занять несколько минут.

После окончания, в папке, указанной на закладке «Project» в пункте «Destination directory», появится каталог html, в котором необходимо найти файл index.html и запустить. Вы должны увидеть нечто вроде:

Doxygen, помимо того, что обработал исходники, так же нашёл документацию и включил её в общую структуру. Среди прочего, он ищет папки с именами docs/doc/manual/etc (список настраивается в экспертном режиме работы), берёт оттуда файлы и включает их в общую структуру. Кстати, сама документацию GRASS обработана так же с помощью этой программы.

Далее встаёт вопрос поиска необходимого кода, в этом может помочь чтение документации и изучение соответствующих функций программы. В нашем случае, зная, что команда трансформации называется g.transform, ищем соответствующий ей код: grass-6.2.3/general/g.transform/crs.c|h. В данном случае сложно найти общий подход, как правило локализовать необходимый код.

Раскрываем слева в дереве пункт «File list» и ищем необходимые файлы.

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

Результаты

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

В приложении к статье Вы можете найти данный класс и пример его использования в MSVC++ 8.0.

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

Когда мы пишем код, наибольшей головной болью является руководство. Многие коды пишут определенный код при написании руководств. Doxygen в основном решает проблемы, возникающие вручную. Когда мы пишем код, мы можем преобразовывать комментарии в руководства. Graphviz в основном используется для Графический дисплей, HTML Help Help в основном используется для создания документов CHM.
1.Doxygen

Doxygen может конвертировать определенные комментарии в программе в файлы инструкций. Он может генерировать чистое справочное руководство на основе структуры самой программы, обрабатывая аннотации в программе в соответствии со спецификациями, извлекая структуру кода или с помощью автоматически генерируемых графов зависимостей, диаграмм наследования и Диаграмма сотрудничества (диаграмма сотрудничества) для визуализации взаимосвязи между документами; формат справочного документа, генерируемого Doxygen, может быть CHM, RTF, PostScript, PDF, HTML и т. Д.

2.graphviz

Graphviz (Программное обеспечение для визуализации графиков) - это набор инструментов с открытым исходным кодом, запущенный AT & T Labs для рисования графиков, описанных в сценариях языка DOT. Чтобы использовать Doxygen для создания графиков зависимостей, графиков наследования и графиков совместной работы, сначала необходимо установить программное обеспечение graphviz.

3.HTML Help WorkShop

HTML Help WorkShop от Microsoft - лучший инструмент для создания файлов CHM, который может компилировать файлы HTML для создания файлов CHM. Программное обеспечение Doxygen генерирует HTML-файлы или латексные файлы по умолчанию. Если мы хотим генерировать документы CHM через HTML, нам нужно установить программное обеспечение HTML Help WorkShop и связаться с Doxygen.

Смотрите пример визуализации.

Загрузка Doxygen (doxygen-1.8.7-setup.exe):

Graphviz (для Windows) скачать:

HTML Help WorkShop (1.32) скачать:

Выберите метод установки программного обеспечения по умолчанию, нажимайте кнопку «Далее», пока установка не будет завершена. После установки вам необходимо связать путь установки graphviz и HTML Help WorkShop при настройке Doxygen.

Все наши настройки выполняются в Doxywizard, и справочное руководство генерируется при запуске Doxywizard.

1.Wizard->Project

Самое важное в Wizard-> Project - это настройка рабочего каталога, каталога исходного кода и каталога сгенерированного справочного файла.Другие имена проектов, описания проектов, версии и логотипы могут быть выбраны в соответствии с фактическими условиями.
Рабочий каталог является вновь созданным каталогом. После завершения настройки файл конфигурации может быть сохранен в этом каталоге. Каждый раз, когда файл конфигурации (.cfg) импортируется из этого каталога, генерируется файл описания ,
Каталог исходного кода и каталог конечных результатов устанавливаются при каждом запуске Doxywizard.

2.Wizard->Mode

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

3.Wizard->Output

4.Wizard->Diagrams

Выберите элемент инструмента точка и используйте GraphViz для рисования.

5.Expert->Project

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

6.Expert->Input

Измените метод кодирования ввода на метод GBK, чтобы вывод не приводил к искаженным символам из-за метода UTF-8.
Последняя и часто встречающаяся проблема заключается в том, что китайский язык в древовидной директории слева от файла CHM, созданного DoxyGen, становится искаженным. Для этого нужно только изменить тип кодировки индекса chm на GB2312. Введите GB2312 в CHM_INDEX_ENCODING HTML.

7.Expert->HTML

Проверьте элемент Generate HTMLHELP, введите имя сгенерированного CHM, введите путь hhc.exe в каталоге установки HTMLHELP WORKSHOP в HHC_LOCATION и измените метод кодирования chm на GBK, что соответствует методу кодирования ввода на шаге (6).

8.Expert->Dot

Введите путь установки GraphViz в Dot_PATH.

Вам необходимо настроить EXTRACT_ALL и LOCAL_METHODS в сборке для генерации всех переменных и функций.

9. Хранить информацию о конфигурации

Хранить информацию о конфигурации. На предыдущем шаге Doxygen был полностью настроен, и вы можете щелкнуть, чтобы запустить его в Run, но чтобы сохранить вышеуказанную информацию о конфигурации, вы можете сохранить сконфигурированный файл в файле .cfg, а затем вам нужно только открыть файл с помощью Doxygen, когда вы запускаете Doxygen. Измените входные и выходные каталоги и информацию о проекте в шаге (1) перед запуском. Файл-> Сохранить как, выберите имя, по умолчанию Doxyfile, добавьте .cfg и нажмите Сохранить. Если вам нужно изменить файл конфигурации, сохраните и замените предыдущий файл конфигурации после изменения.

Краткое описание спецификаций

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

Стиль JavaDoc, используйте две звездочки '*' в начале блока комментариев стиля C:

Комментарии к коду стиля Qt, то есть добавьте восклицательный знак «!» В начале блока комментариев стиля C:

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

Аналогично, краткое описание (краткое) может быть идентифицировано несколькими способами. Рекомендуется использовать команду @brief, чтобы вызвать описание, например

Обратите внимание на следующие моменты:

1. Doxygen не обрабатывает все комментарии, doxygen фокусируется на комментариях, связанных со структурой программы, таких как: файл, класс, структура, функция, глобальная переменная, макрос и другие комментарии,Игнорировать комментарии к локальным переменным, коду и т. Д. В функции。
2. Комментарий должен быть написан перед соответствующей функцией или переменной. В стиле JavaDoc текст перед первым периодом "." Автоматически воспринимается как краткий комментарий, а следующий - подробный комментарий. Вы также можете использовать пустые строки, чтобы отделить краткие комментарии от подробных комментариев. Обратите внимание, чтобы установить для JAVADOC_AUTOBRIEF или QT_AUTOBRIEF значение YES.
3. Сначала начните комментировать из файла, а затем - глобальные функции, структуры, переменные перечисления, пространство имен → классы в пространстве имен → функции-члены и переменные-члены файла.
4. Doxygen не может экспортировать документы для классов, определенных в DLL.

Общие инструкции

модуль

Модули - это способ группировать вещи на отдельных страницах. Членами группы могут быть файл, пространство имен, классы, функции, переменные, перечисления, определения типов и определения, но они также могут быть другими группами.
Чтобы определить группу, \ defgroup должен быть помещен в специальный блок комментариев. Первый параметр команды должен быть меткой, однозначно идентифицирующей группу. Чтобы классифицировать сущность как члена группы, поместите команду \ ingroup перед сущностью. Вторым параметром является название группы.
Чтобы не размещать команду \ ingroup перед каждым членом в комментарии, вы можете заключить его в @ . Тег @ можно разместить в комментариях группы или в отдельном блоке комментариев.
Группы маркеров, использующие эти группы, также могут быть вложенными.
Если групповой тег используется несколько раз, произойдет ошибка. Если вы не хотите, чтобы doxygen применял уникальные теги, вы можете использовать \ addtogroup вместо \ defgroup. Операция очень похожа на \ defgroup, но если группа уже определена, она добавит новый элемент в существующий комментарий по умолчанию. Заголовок группы не является обязательным для этой команды, вы также можете рассмотреть возможность его использования.

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

Блокировать или использовать.

Пример аннотации

1. Файл комментариев
В качестве примера напишите этот комментарий в заголовке файла кода. Вы можете видеть, что вы можете пометить некоторые текстовые имена, авторов, электронные письма, версии, даты, введения и подробные записи версий.

После компиляции с помощью doxygen откройте веб-страницу для отображения следующего: Ниже приведено имя, а значение не объяснено.

2. Класс и комментарии членов

Если комментарии к документам делаются для членов файлов, структур, объединений, классов или перечислений, и комментарии должны добавляться среди членов, и эти комментарии часто следуют за каждым членом. Для этого вы можете использовать знак «<» в разделе комментариев.

Пример аннотации для класса следующий:

3. Функциональные комментарии

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

После открытия веб-страницы аннотации она отображается следующим образом.

4. Перечень примечаний

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

5. Глобальные переменные и макросы

6. Примечания к модулю
Группа определяет приоритет команды (от высокого до низкого): \ ingroup, \ defgroup, \ addtogroup, \ weakgroup. И \ stronggroup похожа на \ addtogroup с низким приоритетом. Он предназначен для реализации «ленивого» метода определения группы: вы можете использовать высокий приоритет для определения структуры в файле .h и использовать \ stronggroup в файле .cpp, чтобы иерархическая структура в файле .h не повторялась.
При фактическом использовании мы можем видеть конкретную веб-страницу, показанную ниже.

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

Выше было объяснено, что это язык C, а язык C. не имеет наследования. Иногда необходимо показать наследование в C ++. Как показано

Скачиваем Doxywizard

При скачивании Doxygen также получаем и Doxywizard. Дополнительные ссылки для скачивания можно найти на странице загрузок Doxygen.

Интерфейс генератора Doxywizard выглядит так:

Отображение документации Doxygen будет таким:

Сам Doxywizard необязательно использовать. Можно генерировать Doxygen с помощью файла конфигурации. Как правило, разработчики запускают сборки Doxygen с сервера.

В отличие от Javadoc, Doxygen позволяет включать внешние файлы, записанные в Markdown. И Doxygen предоставляет функцию поиска. Это две особенности, которые отсутствуют в Javadoc.

Doxygen поддерживается одним разработчиком и, как и Javadoc, не сильно изменился за долгие годы. Интерфейс может быть, сильно устарел и несколько запутан. Но разработчики C++ привыкнут к этому.

Автоматическая интеграция сборок

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

Другие генераторы документации

Не нужно ограничивать себя либо Javadoc, либо Doxygen. Существуют десятки различных генераторов документов для разных языков. По запросу «генератор документов + » можно найти много инструментов. Тем не менее, не стоит увлекаться такими инструментов. Генераторы документов несколько устарели, создают статические интерфейсы, которые выглядят такими же устаревшими, часто написаны инженерами для других инженеров и не очень гибкие.

Возможно, самым большим разочарованием для генераторов документов является то, что в них нельзя интегрировать остальную часть своей документации. Например, застряли с выводом справочной документации. Еще необходимо сгенерировать практические руководства и другие учебные пособия, а затем создать ссылку на справочную документацию. Таким образом, не будет единого интегрированного опыта документирования. Кроме того, будет трудно создавать встроенные ссылки в разделах между двумя выходами. Тема фрагментации результатов подробно рассматривали в разделе Интеграция Swagger с документацией.

Читайте также: