MQL5 代码自动生成文档

Paul | 19 五月, 2014

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 附带的帮助文件相同。

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 中的文件的说明