MQL5 代码自动生成文档
1. 简介
大多数 Java 代码编写者熟悉可通过 JavaDocs 创建的自动生成文档。其思路是以一种半结构化的方式向代码添加注释,然后可以将这些注释提取到易于导航的帮助文件。
C++ 世界也有若干文档自动生成器,其中微软的 SandCastle 和 Doxygen 是两款领先产品。我决定看一看 Doxygen 对创建 MQL5 文档有多少用处,而 MQL5 实质上是 C++ 的一个自定义子集。对我而言,这是熟悉 MQL5 的重要一步,因为语言的复杂性能够轻松地培养某些相当大的类库。
试验非常成功,我认为 Doxygen 从 MQL5 代码生成的帮助文档会增加很多价值。
2. Doxygen
Doxygen 是一款开源自动文档生成器,可通过 GNU 通用公共许可获得,意味着其开发与其它开源项目(例如 Linux 和 Mozilla )类似。Doxygen 是免费下载和使用的,其源代码是公开的,可供任何人查看,并且它是由若干开发人员共同开发和强化的,这些开发人员贡献了他们的时间。
就其最基本的用途而言,Doxygen 简单地解析了一个项目中的所有 C++(或 MQL5)代码,将在一个易于导航的帮助文件中显示其结构。这对面向对象的代码集特别有用,此类代码集一般都有一个大范围的类层次和大量的成员函数。要完全使用 Doxygen 功能,应在代码中写入结构化注释,从而让 Doxygen 能够阅读它们并将信息添加到生成的帮助文件。
2.1 下载 Doxygen
Doxygen 的主页是 http://www.doxygen.org/。您可以从那里导航到下载页面并下载最新的 Windows 版本。在撰写本文时,最新版本是 doxygen-1.6.1,如下所示
图 1. Doxygen 下载
2.2 配置和运行 Doxygen
除了添加 *.mqh 和 *.mq5 文件类型并启动 HTML 帮助的生成以外,几乎不需要做任何事情。以下五张图说明了配置过程。
前四个屏幕截图(图 2 至 5)说明 Wizard(向导)屏幕:
图 2. 配置 Doxygen - 向导 1
图 3. 配置 Doxygen - 向导 2
图 4. 配置 Doxygen - 向导 3
图 5. 配置 Doxygen - 向导 4
最后,有一个用于添加 mqh 和 mq5 文件类型的专家级更改:
图 6. 配置 Doxygen - 包括 mqh 和 mq5 文件
现在,它就可以运行了。请注意,Doxgyen 将存储和读取一个配置文件,该文件包含在本文附带的 zip 附件中。
图 7. 运行 Doxygen
2.3 使用 Doxygen
Doxygen 有一个优秀的经过编译的 html 帮助文件(当然采用 Doxygen 进行构建 - 这是原始 html 版本),该帮助文件详细说明一组令人赞叹的文档功能,包括复杂数学公式的完美显示。然而,这个工具还可用于以一种非常简单的方式创建有用的帮助文件。
以下是 MQL5/Include/Oscilators.mqh 中 CiMACD::Create() 函数的例子。请注意,这些指标文件原本不是早期测试版本的一部分,您可能需要重新下载 MetaTtrader 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. 在 Doxygen 生成的 HTML 中看到的 CiMACD::Create()
2.4 在完全分发的 MQL5 代码集中使用 Doxygen
最能发挥 Doxygen 作用的地方是为大型项目创建帮助文件。使用 MetaTrader 5 在 MQL5 文件夹中分发了超过 100 个的 .mq5 和 .mqh 文件,其中很多是相关的。
我写了一个工具脚本 MetaquotesCommentsToDoxygen.mq5(包含在附带的 zip 文件中),执行上述基本的 Metaquotes 至 Doxygen 注释转换。这不是生成帮助文件的至关重要的一步,但是它提供了 Doxygen 有用的其它文档功能的一个演示。
我用于生成 MQL5 代码集帮助文件的过程如下
- 将 MQL5 文件夹和子文件夹复制到 MQL5/files
- 删除 MQL5/files/MQL5/Include/Strings/string.mqh - 不知为何,此文件阻止 Doxygen 完成其代码解析
对于来自结构化注释的其它文档,进行以下操作(可选):
- 从 MQL5/Files 文件夹,运行 Windows/DOS 命令 xcopy *.mq* c:\ /S/L > MQL5codeList.txt
- 在任何图表上执行 MetaquotesCommentsToDoxygen.mq5 脚本
生成的帮助文档质量优秀,并且快速演示了其有效性 - 图 9 至 12 是你会看到的例子
图 9. Doxygen 生成的类列表
图 10. Doxygen 生成的 CArrayObj 的类树图
图 11. Doxygen 生成的 CArrayObj 的成员函数列表
图 12. Doxygen 生成的定义列表
3. Microsoft 的 HTML Help Workshop
要让 Doxygen 的输出更加有用,还需要进一步处理。Doxygen 生成一个 index.html 文件,该文件指向大量的其它 html 文件和图片。实质上,它类似一个小型网站,因此对于分发而言非常麻烦。
很久以前,微软意识到 Windows 应用程序的帮助文件应以 html 的格式编写,因此他们据此目的开发了 HTML Help Workshop。HTML Help Workshop 采用来自 Doxygen 等输出的帮助文件集,并将文件集编译成一个 .chm 文件。此格式与 MetaTrader 5 附带的帮助文件相同。
单击这里,您就可以从微软网页下载并安装l htmlhelp.exe。
图 13 下载 HTML Help
3.2 创建经过编译的 HTML 帮助文件Doxygen 处理的输出可以通过 HTML Help Workshop 轻松转换成一个经过编译的 html 帮助文件。如针对本文的配置,Doxygen 生成一个 index.hhp 文件,该文件可供 HTML Help Workshop 打开,如下面的图 14 所示。
图 14. Doxygen 生成的 index.hhp 文件的位置
下一步是编译:
图 15 用 HTML Help 进行编译
... 完成时,可以将新的 index .chm 文件复制到 MetaTrader 5/Help 文件夹并重命名,如下面的图 16 和图 17 所示。
图 16. index.chm 位置
图 17. 复制到 help 文件夹并重命名的 index.chm
4. 总结
本练习让我决定在将来使用 Doxygen 或类似软件来说明我想让人们理解并使用的任何 MQL5 代码,并且我希望其他人也是如此。
附录附带的 Doxygen files.zip 中的文件的说明
文件 |
说明 |
复制到 |
---|---|---|
MQL5 codeset help.chm | 随 2009 年 12 月 8 日发布的 MetaTrader 5 build 229 一起分发的所有代码的经过编译的 HTML 帮助文件。 | MetaTrader 5/Help |
MetaquotesCommentsToDoxygen.mq5 | 修改 MQL5 代码中的注释从而让 Doxygen 能够解释它们的脚本 | MQL5/Scripts |
MQL5codeList.txt | 所有分发的 MQL5 文件的列表 | MQL5/Files |
MQL5_Doxygen | Doxygen 配置文件 | MQL5 |
本文由MetaQuotes Ltd译自英文
原文地址: https://www.mql5.com/en/articles/12