Автоматическое создание документации к программам на 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