Автоматическое создание документации к программам на MQL5
1. Введение
Большинство 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
Сайт программы Doxygen - www.doxygen.org. Там можно найти страницу download и скачать последнюю версию Doxygen для Windows. При написании статьи была версия doxygen-1.6.1, как показано на рис 1:
Рис 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.
//+------------------------------------------------------------------+ //| Create indicator "Moving Averages Convergence-Divergence". | //| INPUT: symbol -chart symbol, | //| period -chart period, | //| fast_ema_period -period fast EMA, | //| slow_ema_period -period slow EMA, | //| signal_period -period signal MA, | //| applied -what used. | //| OUTPUT: true-if successful, false otherwise. | //| REMARK: no. | //+------------------------------------------------------------------+ bool CiMACD::Create(string symbol, ENUM_TIMEFRAMES period, int fast_ema_period, int slow_ema_period, int signal_period, int applied)
Некоторые простые изменения ключевых слов позволят программе Doxygen правильно интрепретировать комментарии.
Для этого комментарии должны быть вида "///" (вместо "//"), в описании входных параметров "INPUT:" нужно заменить на "\param", а "OUTPUT:" на "\return".
//+------------------------------------------------------------------+ /// Create indicator "Moving Averages Convergence-Divergence". /// \param symbol -chart symbol, /// \param period -chart period, /// \param fast_ema_period -period fast EMA, /// \param slow_ema_period -period slow EMA, /// \param signal_period -period signal MA, /// \param applied -what used. /// \return true-if successful, false otherwise. //+------------------------------------------------------------------+ bool CiMACD::Create(string symbol, ENUM_TIMEFRAMES period, int fast_ema_period, int slow_ema_period, int signal_period, int applied)
После обработки программой 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
... когда она завершена, можно скопировать и переменовать созданный файл index.chm в папку MetaTrader 5/Help, как показано ниже на рис. 16 и 17.
Рис 16. Местонахождение созданного файла справки index.chm
Рис 17. Копируем index.chm в каталог справки MQL и переименовываем его в MQL5 codeset help.chm
4. Итоги
Результаты данной работы убедили меня использовать Doxygen (или похожие программы) в будущем для создания документации к любому моему коду на MQL5, это значительно облегчает его понимание и использование. Надеюсь, что другие авторы также найдут Doxygen полезным.
Приложение. Описание файлов прилагаемого архива Doxygen files.zip
Файл |
Описание |
Каталог для копирования |
---|---|---|
MQL5 codeset help.chm | Скомпилированный файл справки HTML для всего кода, входящего в поставку MetaTrader 5 build 229 от 8 декабря 2009. | MetaTrader 5/Help |
MetaquotesCommentsToDoxygen.mq5 | Скрипт, который модифицирует комментарии в коде на MQL5, таким образом, чтобы Doxygen смог их интерпретировать | MQL5/Scripts |
MQL5codeList.txt | Список файлов, поставляемых с MQL5 | MQL5/Files |
MQL5_Doxygen | Конфигурационный файл Doxygen configuration file | MQL5 |
Перевод с английского произведен MetaQuotes Ltd.
Оригинальная статья: https://www.mql5.com/en/articles/12
- Бесплатные приложения для трейдинга
- 8 000+ сигналов для копирования
- Экономические новости для анализа финансовых рынков
Вы принимаете политику сайта и условия использования
Вроде общепринято @param вместо \param для совместимости с другими докогенераторами.
Будет замечательно, если принять этот стандарт на уровне MQL, а то настоящий стиль комментирования кода странный - много лишних //////.
А если добавить поддержку на уровне MetaEditor, как это сделано в Eclipse... ммм...
Версия 1.8.7 последняя с поддержкой MQL.
Баг где-то среди этих коммитов.
Кто найдет - сообщите.
Версия 1.8.7 последняя с поддержкой MQL.
Баг где-то среди этих коммитов.
Кто найдет - сообщите.