Скачать MetaTrader 5

Автоматическое создание документации к программам на MQL5

23 ноября 2009, 17:57
Paul
9
4 418

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:

Загрузка Doxygen

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

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

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

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

Настройка Doxygen - Wizard 1

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

Настройка Doxygen - Wizard 2

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

Настройка Doxygen - Wizard 3

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

Настройка Doxygen - Wizard 4

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

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

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

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

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

Запуск Doxygen

Рис 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:

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

Рис 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.

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

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

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

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

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

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

Список определений (defines), созданные 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.

Загрузка HTML Help Workshop

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

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

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

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

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

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

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

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

... когда она завершена, можно скопировать и переменовать созданный файл index.chm в папку MetaTrader 5/Help, как показано ниже на рис. 16 и 17.

Местонахождение созданного файла справки index.chm

Рис 16. Местонахождение созданного файла справки index.chm

Копируем index.chm в каталог справки MQL и переименовываем его в MQL5 codeset help.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 Software Corp.
Оригинальная статья: https://www.mql5.com/en/articles/12

Прикрепленные файлы |
doxygen_files.zip (1933.39 KB)
Automated-Trading
Automated-Trading | 17 мар 2010 в 17:59
GarF1eld писал(а) # :
Проще на вкладке Input задать INPUT_ENCODING как windows-1251. И никаких проблем с кодировками

конечно так было бы проще.

но почему-то doxygen (у меня 1.6.2) во все файлы вставляет

<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>

хотя в настройках

т.е файлы в нужной кодировке, а отображение можно исправить если во всех html-файлах заменить на:

<meta http-equiv="Content-Type" content="text/xhtml;charset=windows1251"/>

но вопрос в том, как побороть его, чтобы он это делал самостоятельно.
Alexander
Alexander | 17 мар 2010 в 20:40
Честно говоря не замечал, т.к меня вполне устраивает UTF-8, а когда была проблема с крокозяблами, просто изменил INPUT_ENCODING
Roffild
Roffild | 5 апр 2013 в 13:35

Вроде общепринято @param вместо \param для совместимости с другими докогенераторами.

Будет замечательно, если принять этот стандарт на уровне MQL, а то настоящий стиль комментирования кода странный - много лишних //////.

А если добавить поддержку на уровне MetaEditor, как это сделано в Eclipse... ммм...

Roffild
Roffild | 7 апр 2015 в 07:33

Версия 1.8.7 последняя с поддержкой MQL.

Баг где-то среди этих коммитов.

Кто найдет - сообщите.

Denis Savenko
Denis Savenko | 19 май 2015 в 17:05
Roffild:

Версия 1.8.7 последняя с поддержкой MQL.

Баг где-то среди этих коммитов.

Кто найдет - сообщите.

Спасибо. Все перерыл пока боролся последними версиями( Да выше 1.8.7 не идет. По коммитам так и не понял в чём подвох(
Паттерны, доступные при торговле корзинами валют. Часть II Паттерны, доступные при торговле корзинами валют. Часть II

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

Универсальный тренд с графическим интерфейсом Универсальный тренд с графическим интерфейсом

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

Переход на новые рельсы: пользовательские индикаторы в MQL5 Переход на новые рельсы: пользовательские индикаторы в MQL5

Я не буду перечислять все новые возможности и особенности нового терминала и языка. Их действительно много, и некоторые новинки вполне достойны освещения в отдельной статье. Вы не увидите здесь кода, написанного по принципам объектно-ориентированного программирования — это слишком серьезная тема для того, чтобы просто быть упомянутой в контексте как дополнительная вкусность для кодописателей. В этой статье остановимся подробней на индикаторах, их строении, отображении, видах, а также особенностях их написания по сравнению с MQL4.

Вот мы и получили долгожданные MetaTrader 5 и MQL5 Вот мы и получили долгожданные MetaTrader 5 и MQL5

Это очень краткий обзор MetaTrader 5. Я не могу описать все новшества системы за столь короткий период времени - тестирование стартовало 09-09-2009. Это символическая дата, и я уверен, что это будет счастливым числом. Всего несколько дней у меня на руках бета-версия терминала MetaTrader 5 и MQL5. Я не успел опробовать все, что в нем есть нового, но то, что есть, уже впечатляет.