下载MetaTrader 5

MQL5 代码自动生成文档

19 五月 2014, 08:18
Paul
0
895

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:变为 \paramOUTPUT:变为 \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 附带的帮助文件相同。

3.1 下载 HTML Help Workshop

单击这里,您就可以从微软网页下载并安装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 Software Corp.从英文翻译成
原始文章: https://www.mql5.com/en/articles/12

附加的文件 |
doxygen_files.zip (1933.39 KB)
利用 MQL5 向导和 Hlaiman EA 生成器创建神经网络 EA 利用 MQL5 向导和 Hlaiman EA 生成器创建神经网络 EA

本文讲述的是利用 MQL5 向导和 Hlaiman EA 生成器自动创建神经网络 EA 的一种方法。向您展示如何轻松开始神经网络的使用,且无需学习整体的理论知识,也不必编写自己的代码。

另一个 MQL5 OOP 类 另一个 MQL5 OOP 类

本文会从一种理论性交易概念的构想,到编制一个在经验世界中实现这一概念的 MQL5 EA 交易,为您讲解如何从头建立一个面向对象的 EA 交易。依本人看,边做边学是取得成功的一种可靠方法。所以,我会拿出一个实用的例子,让您明白如何才能整理自己的想法,并最终完成外汇自动交易代码。和您一起遵守“面向对象”原则,也是我的目标之一。

用 MQL5 向导创建您自己的 EA 交易 用 MQL5 向导创建您自己的 EA 交易

编程语言知识不再是创建自动交易的一个先决条件。以前,缺乏编程技能是实现自己的交易策略的不可逾越的障碍,但是随着 MQL5 向导的出现,这种情况迅速改变了。交易新手能够不再因为缺乏编程经验而担心 - 使用让您能够生成 EA 代码的新向导,编程经验不再是必不可少的了。

如何向 MetaTrader 5 平台添加新的用户界面语言 如何向 MetaTrader 5 平台添加新的用户界面语言

MetaTrader 5 平台的用户界面被翻译成几种语言。如果您的母语不在支持的语言之中,请不用担心。您可以使用的特别的 MetaTrader 5 MultiLanguage Pack 工具轻松地完成翻译,这个工具由 MetaQuotes Software Corp. 提供,对所有用户都是免费的。在本文中,我们将介绍几个如何向 MetaTrader 5 平台添加新的用户界面语言的例子。