1. Введення
У світі C ++ також є кілька автоматичних генераторів документації, одними з лідерів є програми Microsoft's SandCastle і Doxygen.
Я вирішив перевірити, наскільки добре Doxygen зможе документувати MQL5, який, по суті, є підмножиною C ++. На мій погляд, підтримка об'єктно-орієнтованого програмування - це важливий крок в зрілості MQL5, оскільки тепер мова дозволяє створювати великі бібліотеки класів. Цей експеримент вдався, і я сподіваюся, що документація, створювана програмою Doxygen з MQL5-коду, буде дуже корисна.
2. Програма Doxygen
Програма Doxygen є системою автоматичного створення документації c відкритим вихідним кодом згідно з GNU General Public License. Це означає, що її розробка була схожа на інші проекти з відкритим кодом, такі як Linux і Mozilla. Її можна безкоштовно завантажити і використовувати, вихідний код 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.
Після обробки програмою Doxygen, файл довідки буде виглядати, як показано на рис. 8:
Рис 8. Опис функції CiMACD :: Create (), створене Doxygen
2.4 Використовуємо Doxygen для документування всього код, який надається з MQL5
Сила Doxygen - в створенні файлів довідки для великих проектів. Склад поставки MetaTrader 5 (каталог MQL5) містить більше сотні файлів .mq5 і .mqh, багато з яких пов'язані між собою.
Для створення довідки по всьому коду MQL5, що поставляється з MetaTrader, потрібно зробити наступне:
- Скопіювати вміст каталогу MQL5 разом підкаталогами в каталог MQL5 / files.
- Видалити файл MQL5 / files / MQL5 / Include / Strings / string.mqh - з невідомої причини Doxygen не може його правильно інтерпретувати.
Отримана в результаті документація має хорошу якість і швидко демонструє свою користь - приклади наведені на рис 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