基于 MQL5 源代码创建文档

Andrei Novichkov | 17 八月, 2017


概述

开发者通常需要为其代码创建文档。编写说明和用户手册是日常活动, 且为与客户沟通的重要组成部分。此外, 随着时间的推移, 我们积累了很多不同的函数库和代码片段, 其中包括其他开发者编写的函数库和代码片段。结构良好的文档可以帮助您更轻松地了解这些素材。当开发代码时如果我们牢记需要编写手册, 这个任务不需要额外的时间。所需的注释和标签会在代码创建的同时加入。第一感觉, 这个任务可能看起来并非必要, 但如果这样做, 可在后来为开发者节省大量的时间和精力。

我们来从头到尾研究文档创建过程, 同时详细分析最重要的关键点。之前已经写过相关的 文章, 但其中描述的一些信息和方法没有更多的相关性。我们尝试进一步拓展这个话题。我们主要研究使用 Doxygen 软件和 Doxywizard.exe。

将 MQL 文件添加到 Doxygen

我们的目标是将位于一个或多个文件中的已编写代码根据现有标记来创建一个帮助/演示文档。作为结果, 我们将得到 chm 格式的文件。此外, 我们还将创建 html 文件, 它也可用于演示或参考目的。我们将使用 Doxygen 软件, 它很适合上述任务。

在 上面提及的文章 中描述了程序设置过程和结果文件的输出。但它是在很久以前发表的, 且那些曾描述过的指令如今已不能正常工作。如果我们遵循那些描述, 程序运行不会有警告和错误消息, 但却不会创建文件。

所以, 我们首先要做的事情就是更新程序配置描述。启动 doxywizard.exe 进行配置: 指定您的项目名称, 输入和输出文件夹, 并确认在 向导 选卡的 模式 部分选择 "优化为 C++ 输出" 选项。

打开 智能程序 选卡, 并在 输入 部分添加带有所需扩展名的文件:

现在 Doxygen 将会明白它需要使用扩展名解析文件。但这还不够！我们需要为程序明确指定带有 .mq* 扩展名的文件等同于带有 .с 扩展名的文件, 即, "映射" 文件:

从现在开始, Doxygen 开始解析我们的文件并生成结果。

编码


另一个在上篇文章中未涉及的问题与源码和结果文档的编码有关。

如果文档语言是英文, 则没有问题。但是, 如果我们打算用另一种语言创建文档, 我们可能会得到不可读的字符。原因如下。省缺情况下, 所有文档均以 UTF-8 编码格式创建。如果文档的一部分具有不同编码, 则文本可能变得不可读。我们来研究以下解决方案:

  1. 我们来检测省缺的语言和编码。我们将使用 UTF-8 和俄语:





    应当注意的是, 我并未设法改变 DOXYFILE_ENCODING。无论在这个输入字段中指定了何种编码, UTF-8 均会无条件加入。大概, 唯一改变编码的方法是在文件中明确指定, 即应该替换 "Head"。不过, 以这种方式难以达到预期的结果。

  2. 我们需要指定源文档的编码, 它可能与 UTF-8 不同。在我们的示例中, 源编码是 CP1251。如果不同源文档中的编码不同, 我们需要更改编码, 以便对所有源文档使用单一编码。我们需要在此输入字段中写入:




  3. 由于我们要以 CHM 格式输出, 我们需要明确指定 HtmlHelp 索引中使用的编码 (带有 hhk 扩展名的文件):




    对于那些希望更详细地了解这个过程的人, 我附上了一篇关于如何使用 Doxygen 创建西班牙语和英语文档的文章。

现在, 我们来看看更多的常见要点, 这些要点似乎是很重要, 特别是生成 html 文件的外观。


页面页眉和注脚

可用选项位于 智能程序 选卡的 HTML 部分。一个有用的切换器工具允许连接自定义 html 文件来创建最终文档, 即, HTML_HEADER, HTML_FOOTER 和 HTML_STYLESHEET 字段。根据字段名称, 我们可以了解它们负责的内容: 每个页面的页眉, 每个页面的注脚, 以及显示样式。记住, 应在选卡上打开 GENERATE_HTML 切换器, 以便生成 html 文件。

分析过的 html 文件均基于特殊规则编写, 虽然对于 footer.html, 我成功地使用了一段没有抬头和样式的 html 文本:

<div>
  <h1 style="text-align: center;">Footer</h1>
</div>

但最好遵守规则。为了理解如何编排自定义文件, 我们可以通过程序生成省缺文件。除了两个期望的 html 文件之外, 我们还得到一个样式表。我们使用以下命令完成它:

 - doxygen -w html new_header.html new_footer.html new_stylesheet.css

这是 new_footer.html 文件的一部分:

<!-- HTML footer for doxygen 1.8.13-->
<!-- start footer part -->
<!--BEGIN GENERATE_TREEVIEW-->
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
  <ul>
    $navpath
    <li class="footer">$generatedby
    <a href="http://www.doxygen.org/index.html">
    <img class="footer" src="$relpath^doxygen.png" alt="doxygen"/></a> $doxygenversion </li>
  </ul>
</div>
<!--END GENERATE_TREEVIEW-->
<!--BEGIN !GENERATE_TREEVIEW-->
<hr class="footer"/><address class="footer"><small>
$generatedby &#160;<a href="http://www.doxygen.org/index.html">
<img class="footer" src="$relpath^doxygen.png" alt="doxygen"/>
</a> $doxygenversion
</small></address>

如您所见, 在此看到许多占位符, 其清单和目的已在文档中描述过。您可以轻松地了解 Doxygen 显示广告的位置, 以及可以放置链接的位置。类似地, 您可以编辑 new_header.html 和样式表 (如有必要), 然后在指定的选项卡上启用它们。因此, 您可以显式修改生成的文档外观。


预处理

Doxygen 支持预处理文件, 即程序可以处理诸如 BEGIN_MESSAGE_MAP 的宏指令, 以及诸如来自 Visual Studio 的 __declspec 结构。这对于我们的脚本来说并不重要, 所以我们在这里只提到这个可能性, 而无需进一步的细节。此机制在“智能程序" 选项卡的 "预处理器" 部分中设置。也可以创建外部过滤器。这些过滤器的目的是转换输入文件, 以便 Doxygen 可以理解它。这样的过滤器是一个外部控制台程序。已处理文件的名称将添加到其命令行。过滤程序本身基本上是一组正则表达式, 例如, 将汇编器中的程序转换为 Doxygen 可以理解的形式。开发者应决定是否采用预处理。例如, 您可以尝试使用此机制转换 #property 结构, 并使得 Doxygen 可以理解。


包括示例

一个非常有趣的可能性就是在文档中包括示例。这并非必须, 但是示例可令文档看起来完整和专业。示例作为一个或多个文件包含在项目中。为了做到这一点, 下面的代码应该添加到页面中, 开发者希望提供一个例子: 
/** \示例文件名.扩展名
 * 这是一个如何使用的实例 ....
 */

含有示例的文件名称在此处设置。在第二行中, 您可以列出示例中要说明的函数或类。但这还不够: 我们还不知道文件所在的位置。含有示例的文件路径应在 Doxygen 中明确指定。我们应该指定文件的路径及其名称的范式。参见下图:


通过添加几条路径, 并使用 EXAMPLE_RECURSIVE 复选框, 我们可以包含多个附有示例的文件, 并得到一个结构良好的帮助文档。


HTML 标签

Doxygen 的另一个有用的功能是可以使用 html 标记的片段, 它可以直接放在注释块中。程序文档具有大量 HTML 标签列表, 可供 Doxygen 处理并插入到最终文档之中。例如, 以下文本将含有标题的链接和表格插入到宏描述中: 
/*!
  \def def_example
  \brief <a href="http://www.google.com">links to google</a>
         <table>
           <caption>Single table</caption>
           <tr>
             <td>One</td>
             <td>two</td>
           </tr>
         </table>
*/
#define def_example "Some define"

伪字符, 譬如 &nbsp; 可以使用 html 标记。

还有一个有趣的功能是使用链接 自动链接生成。实际上, 这意味着 Doxygen 会将文本 https://www.mql5.com 转换为正确的链接, 并将其插入到结果文档。自动链接生成 也可创建文件, 类, 和独立函数的链接。这是一个方便的功能, 用于生成诸如 "另请参见" 之类的部分。 通常来说, 这些标记可以提供对代码片段的更好描述, 可用于 "上一页/下一页" 标记或其它分页表单, 并可用于搜索引擎优化和广告目的。


标题/封面

我们已经说过使用自己的文本替换页眉和注脚的代码可能性。此外, 可以为标题页开发单独的设计。为此目的, 需要在其中一个文件中指定它包含标题页。这可以在文件开头使用 \mainpage 标签来完成: 
/*!\mainpage 我的个人首页
* \image html i.jpg
 */

此标记声明它所在的文件是标题页, 其标题是 "我的个人首页", 后跟 "i.jpg" 图片。图片必须提前准备, 而 Doxygen 的路径应该是已知的:


除图片外, 您还可以插入其它类型的文件。


html 和 HtmlHelp 形式的文档

您可以使用多种格式创建文档。您可在 向导 选项卡的 输出 部分中选取所需的格式。第一个选项是通常的 html 格式。index.html 文件将会在指定的输出文件夹中创建。这将是整个文档的主要文件。不过, 这种格式并不总是很方便。因此, 我们考虑使用 HtmlHelp 格式创建文档。在输出菜单里选择 HTML 和 "准备压缩的 HTML"。另外, 在 智能程序 选项卡 -> HTML -> 输入字段 CHM_FILE, 设置 HtmlHelp 文件名称及扩展名, 并在下面的 (在 HHC_LOCATION) 指定帮助项目编译器 hhc.exe 的路径。它是一个可选参数。如果此字段为空, 程序将准备所有必需的文件, 您还可以额外利用 HTML 帮助工作间 得到 chm 格式的帮助项目。

输出菜单还提供了更多的微调选项。特别应注意 GENERATE_CHI。此选项省缺时禁用。若您启用它, Doxygen 将会生成一个带有 CHI 扩展名的检索文件。若删除此文件也许在使用主帮助文件时会导致问题。几乎整个 HtmlHlp 格式的帮助将失去其大部分功能。

编码选项已经讨论完毕。所以您只需要进入 运行 选项卡, 然后按 运行 Doxygen。在含有技术信息的页面之后, Doxygen 将报告操作完成。下面的 显示 HTML 输出 按钮可以在浏览器中查看生成的文档。HtmlHelp 格式的文件应可手动运行。

以下是使用 Doxywizard 的短视频:


下一步, 我们研究一些次要点, 这些也很有趣。


在 Sublime Text 3 中编辑 MQL5 代码标签 的可能性

为了正确的 Doxygen 操作, 我们需要在文档文本中使用特殊标签。标签可针对代码的单独部分、类、宏、函数等放置在多行和单行注释中。您希望在文档中包含更多信息, 您需要更仔细地构建它, 那么结果会导致更复杂的标签结构。

可以在 MT5 编辑器中添加标签。在此情况下, 有必要仔细监视所有错误。此过程可以稍微简化并部分自动化。我们利用 Sublime Text 3 编辑器。它能识别 MQL4, 也可配合 MQL5 使用。我们在编辑器中启用全部 MQL 相关的软件包。

然后我们安装一个可以处理用必要标记的软件包, DoxyDoxygen。它支持热键, 并有翻译成不同语言的可能性, 且包括自动完成功能。这个软件包将有助于更快地放置适当的标签, 且成本更低廉。文档 (附在本文中) 建议, 在标记之后, 可以直接从编辑器调用 Doxygen。软件包配置过程的描述也可以在下面的附件中找到。

一般来说, 使用所描述的软件包没有任何特别的困难, 所以我们不再赘言。


输出为 pdf 和 djvu 形式

Doxygen 提供了这个有趣的功能, 但其实现尚未完成。不过, 您可以尝试以这些格式输出文档。Doxygen 文档中提供了一些相关信息, 还有关于第三方网站的一些文章和说明。我们来研究以 pdf 格式输出。
  1. 在 向导选项卡的 输出 栏您可以在 LaTeX 选择输出, 并选择 PDF 格式。文档说, 还需要在 智能程序 选项卡, PerlMod中选择 GENERATE_PERLMODE, 但是我们将跳过此步骤。
  2. 配置其它必要的设置, 包括 CHM 和 html (如果需要) 中的输出。
  3. 现在我们来创建文档。

在输出文件夹里将会创建 latex 文件夹, 且在其内创建相应的文件。在 Doxygen 软件中创建文档的步骤已经结束。现在, 我们需要将 latex 文件转换为 PDF。我使用来自 这个源 的 MikTex 软件的便携式版本。安装并运行程序。选择 TeXworks。在编辑器窗口中, 在 latex 文件夹中查找并打开 Doxygen 创建的 refman.tex 。在编辑器工具栏上, 从列表中选择 XeLaTex, 然后单击左侧的绿色大按钮。之后会显示一些诊断信息。在操作期间, 编辑器将提示安装额外的软件包 (您应该同意)。如果输出完成并出现错误, 您可以尝试再次编译文档。

结果就是, 文档的 refman.pdf 文件将在同一 latex 文件夹里创建。尽管如此, 输出质量也远远不够, 您还需要另外编辑文档设计。也许, 通过编辑 latex 文件可以避免许多小瑕疵。但这种可能性的实现还未完成。因此, 我们只好等待 Doxygen 中这个选项的官方通告。

应用

我们转入示例, 看看如何使用 Doxygen 和其它文档相关的软件。我们从标准库的文档开始, 即位于 \MQL5\Include 中的一组类。我们使用一个简单的方法: 在 DoxyGen 中处理所有文件, 而无需在这些文件中添加其它标签。我们不会得到有关函数库元素的其它重要信息, 但我们将能看到结果, 这也是令人满意的。首先, 我们假设计算机上已经安装了所有必需的软件组件。所以, 我们开始吧。

将标准库复制到任意其它文件夹, 以防万一, 尽管我们不会在文件中写任何内容。

  • 运行 Doxygen 并配置它。对于预设, 您可以使用附带的 MQL5Doxygen.zip 文件。如果您要使用自己的文件, 应该相应地重新配置 Doxygen。设置文件所需的路径, 项目名称, 选取编码和语言。
  • 特别注意 向导 选项卡和 输出 部分。输出格式设置为 plain html "使用搜索功能"。这意味着向导不会生成 HtmlHelp文件。若您选择 "准备压缩 HTML (.chm)"", "使用搜索功能" 选项不会被取消选中, 但程序稍后会显示警告, 该选项 不能使用。但是我们需要这两个选项。
  • 所以, 我们将需要执行两次生成过程。在第一次生成过程里使用 MQL5Doxygen.zip 中的简单设置, 我们只接收输出文件夹中 html 格式的文档。文档的开头位于 index.html 中。
  • 用其它设置重复生成。取消选择 "使用搜索功能"。选取 "准备压缩的 HTML (.chm)"。进入 智能程序 选项卡, 指向 HTML。请注意, 有必要设置 CHM_FILE, 即文件 WITH EXTENSION 的名称, HtmlHlp 帮助文件将会据此创建, 以及在 HHC_LOCATION 中的 hhc.exe 编译器路径。如果这些变量未经初始化, Doxygen 将准备 HtmlHlp 项目的原文件, 当然不会创建帮助文件, 您将需要另外运行 HTML 帮助工作间。更改所需的设置之后, 我们就可以开始生成过程。结果就是, 我们将得到 html 格式的文档 (类似于第一次启动, 但没有搜索选项) 和 HtmlHlp 格式的文档。结果和配置文件可在附带的 StandardLibrary.zip 存档中找到, html 文件已从中删除。如果您仍然需要 html 格式的标准库文档, 您可以轻松地生成它。

我们继续下面的例子。这一次, 我们尝试添加所需的标签, 并改进生成的文件外观。

  • 首先, 我们用最简单的测试代码创建两个文件, 并令其 "复杂化"。我们用必需的标签创建一个封面页面 mainpage.mq5。另外, 我们在此标题页面添加图片。所有三个文件 (片像文件除外) 将被放置在 向导 选项卡 项目 部分中定义的 源代码目录 中。此处我们还定义了输出文件夹和项目的图标, 如果需要的话。
  • 我们为图片创建一个文件夹, 并保存图片文件。现在, 我们通过编辑脚本 Doxygen 使用的文件来创建 footer.html 文件。目的是删除 Doxygen 的广告。您可以在此处添加其它内容, 但请注意, 文件中的警告 "需要树状视图功能！" 提醒您在编辑时应多加留意。我们来修改设置并指定图片的位置和新的注脚文件。这个过程已在前面描述过。
  • 我们使用此代码创建一个带有测试示例的文件, 将其保存到单独的文件夹, 并通知 Doxygen 其位置。
  • 现在我们已经创建了项目结构, 我们可以使用测试代码打开文件并添加所需的标签。我们利用已安装软件包集合的 Sublime Text 3 (这在文章开头已提及)。附带的存档包含一个标记版本, 但还有许多其它可能的变体。
  • 针对 Doxygen 的设置进行最终修改。我们应该提供执行两步输出的可能性, 如前面的例子所述。
  • 执行输出。之后, 我们将得到 HTML 格式的文档。然后我们更改 Doxygen 设置, 并以 HtmlHelp 格式接收文档。

附件 Custom_HTML_CHM.zip 存档中提供了完整项目, 源文件, Doxygen 配置文件和两种格式的生成文档。

结论


本文的目的是为了避免文献引用并使用各种程序替代, 同时专注于能够得到具有吸引力的文档的各种特殊功能。对于那些想要更全面研究所有 Doxygen 标签和开关的人, 我已附带了现有的 CHM 格式软件文档。Sublime Text 3 软件包提供了内置的文档, 而这个编辑器非常受欢迎。

附件说明。

名称 描述
Using_Doxygen_to_generate_Spanish_and_English_documentation.zip PDF 格式的文章
Doxygen_Manual.zip chm 格式的 Doxygen 文档
DoxyDoxygen.zip pdf 格式的 DoxyDoxygen 软件包文档
MQL5Doxygen.zip Doxygen 配置文件
StandardLibrary.zip CHM 格式的结果文档
Custom_HTML_CHM.zip
html 和 CHM 格式的结果文档