风险提示：本文为软件开发与技术服务类技术文章，仅用于MT5 EA程序化交易的技术研发交流与工程化方法论探讨。文中涉及的文档自动化工具、代码示例、配置方案等均为技术原理演示，不构成任何投资建议、交易策略推荐或收益承诺。外汇、贵金属、CFD等杠杆交易存在极高风险，可能导致全部本金损失。读者应根据自身风险承受能力谨慎决策，并独立承担交易后果。
一、为什么90%的EA项目没有文档——痛点与代价
做EA开发超过一年的开发者，几乎都有过这样的经历：三个月前写的一个EA，今天客户说要加个功能，打开源码一看，某个枚举变量的每个值代表什么意思，完全记不起来了；团队里新人接手项目，花了整整两周才读懂核心类的作用，期间问了无数个"这个函数是干嘛的"；更有甚者，自己写的代码，半年后回来看，跟看别人的代码没什么区别——该踩的坑一个没少踩。
这不是记忆力的问题，这是缺乏文档管理意识的必然结果。在EA开发圈子里，"不写文档"几乎是一种默认状态。据我们对国内EA开发者社群的观察，超过90%的独立EA开发者的项目没有正式文档，代码里的注释也是想到哪写到哪，完全不成体系。
不写文档的隐性成本其实远超大多数人的想象。我们来算一笔账：一个3000行代码的中型EA项目，如果没有规范的文档和注释，开发者每次修改功能前需要花2-3小时重新理解相关代码的逻辑；团队协作时，新人上手时间从有文档的3天延长到2周；客户支持方面，文档类问题（"这个参数什么意思""那个函数怎么用"）平均每天要占掉客服30%的工作量。粗略估算下来，没有文档的项目，后期维护成本是有文档项目的3倍以上。
重点：文档不是负担，而是投资——自动化工具可以让文档生成的边际成本趋近于零。很多开发者觉得写文档浪费时间，是因为他们把文档等同于"手动写Word说明书"。但实际上，如果能从代码注释中自动提取生成文档，那么写注释的过程就是在写文档，一次投入、持续产出。本文要讲的，就是如何把MQL5代码中的注释变成专业级的API文档，而且是全自动的。
对于EA开发者来说，文档的价值体现在三个层面：个人层面，三个月后看自己的代码不用重新猜，效率大幅提升；团队层面，新人交接有章可循，代码Review有据可依，协作效率显著提升；产品层面，一份专业的API文档就是EA产品的"门面"，客户看到会觉得这个EA是认真做的，信任感瞬间建立。
接下来，我们就从最基础的注释规范开始，一步步打通MQL5代码文档自动化的全链路。
二、MQL5注释规范：Doxygen风格注释详解
2.1 为什么选择Doxygen
在文档自动化工具的选择上，Doxygen是目前最成熟、应用最广泛的方案之一。它的优势在于：跨语言支持——支持C++、Java、Python等多种语言，MQL5因为语法与C++高度相似，可以通过配置映射过去；输出格式丰富——HTML、CHM、PDF、LaTeX等多种格式都能生成；配置灵活——从简单的一键生成到深度自定义样式，都能满足；生态成熟——大量开源项目在使用，遇到问题容易找到解决方案。
概念：Doxygen是一款开源的文档生成工具，它通过解析源代码中的特定格式注释，自动提取类、函数、变量等元素的说明，生成结构化的API文档。其核心思想是"文档即代码"——文档的来源就是代码中的注释，两者天然同步。
2.2 普通注释 vs 文档注释
很多开发者容易混淆一个概念：普通注释和文档注释不是一回事。普通注释（// 或 /* */）是写给正在读代码的人看的，解释"这里为什么这么写"；而文档注释（/// 或 /** */）是写给要用这段代码的人看的，告诉他"这个东西怎么用"。
重点：注释不是复述代码，而是解释意图和约束。一个好的文档注释不会说"这个函数循环遍历数组"，而是说"这个函数用于计算指定周期内的RSI值，返回值范围为0-100，参数period必须大于等于2"。前者是代码已经告诉你的，后者是代码没说但使用者必须知道的。
2.3 Doxygen常用标签速览
Doxygen通过"标签"来标记注释中不同类型的信息。以下是MQL5开发中最常用的几个标签：
- @brief：简短说明，一句话概括功能
- @param：参数说明，可指定//
- @return：返回值说明
- @note：附加说明/注意事项
- @warning：警告信息
- @details：详细描述
- @file：文件级标记，用于文件头
- @author：作者信息
- @date：日期标记
- @version：版本号
技巧：写代码时先写注释再写实现——先用@brief写清楚函数要做什么，再动手写代码。这样不仅文档有了，代码设计也会更清晰。很多时候你写注释的时候就会发现"这个函数的职责好像不太明确"，这就是在帮你做架构梳理，一举两得。
2.4 MQL5注释示例：CIndicatorManager类
下面是一个完整的MQL5类注释示例，展示了文件级、类级、函数级、枚举级、变量级的规范写法。这个类可以作为你写注释时的模板参考：
//+------------------------------------------------------------------+
//| @file CIndicatorManager.mqh
//| @brief 指标管理类头文件
//| @author 晓辉编程 (eafxtech.com)
//| @date 2026-10-09
//| @version 2.1.0
//+------------------------------------------------------------------+
/**
* @brief 指标类型枚举
* @details 定义了当前支持的所有技术指标类型，
* 用于在创建指标时指定类型。
*/
enum ENUM_INDICATOR_TYPE
{
INDICATOR_MA, ///< 移动平均线 (Moving Average)
INDICATOR_RSI, ///< 相对强弱指标 (Relative Strength Index)
INDICATOR_MACD, ///< MACD指标
INDICATOR_BOLLINGER, ///< 布林带 (Bollinger Bands)
INDICATOR_STOCHASTIC ///< 随机指标 (KDJ)
};
/**
* @brief 指标管理器类
* @details 封装了系统指标的创建、取值与释放，
* 提供统一的接口管理多个技术指标实例。
* 支持MA、RSI、MACD、布林带等常用指标。
* @ingroup Indicators
*/
class CIndicatorManager
{
private:
int m_handle; ///< @brief 指标句柄
string m_indicator_name; ///< @brief 指标名称
int m_period; ///< @brief 指标周期参数
ENUM_TIMEFRAMES m_timeframe; ///< @brief 指标所在时间周期
/**
* @brief 创建指标句柄（内部方法）
* @param type 指标类型
* @param period 计算周期
* @return true=创建成功，false=创建失败
* @warning 仅在InitIndicator内部调用，外部勿直接使用
*/
bool CreateHandle(ENUM_INDICATOR_TYPE type, int period);
public:
CIndicatorManager();
~CIndicatorManager();
/**
* @brief 初始化指标
* @details 根据指定类型和参数创建指标句柄。
* @param type 指标类型（ENUM_INDICATOR_TYPE）
* @param period 计算周期，默认14
* @param timeframe 时间周期，默认当前周期
* @return true=初始化成功，false=失败
* @note 初始化失败时请检查终端是否有该指标权限
*/
bool InitIndicator(ENUM_INDICATOR_TYPE type,
int period=14,
ENUM_TIMEFRAMES timeframe=PERIOD_CURRENT);
/**
* @brief 获取指标值
* @param shift K线索引（0为当前K线）
* @param buffer 缓冲区索引，默认0（主信号线）
* @return 指标值，失败返回EMPTY_VALUE
*/
double GetValue(int shift, int buffer=0);
/**
* @brief 释放指标句柄
* @details 调用IndicatorRelease释放资源，
* 不再使用时必须调用以避免句柄泄漏。
* @return true=释放成功
*/
bool Release();
/**
* @brief 获取指标名称
* @return 指标名称字符串
*/
string GetName() const { return m_indicator_name; }
};
//| @file CIndicatorManager.mqh
//| @brief 指标管理类头文件
//| @author 晓辉编程 (eafxtech.com)
//| @date 2026-10-09
//| @version 2.1.0
//+------------------------------------------------------------------+
/**
* @brief 指标类型枚举
* @details 定义了当前支持的所有技术指标类型，
* 用于在创建指标时指定类型。
*/
enum ENUM_INDICATOR_TYPE
{
INDICATOR_MA, ///< 移动平均线 (Moving Average)
INDICATOR_RSI, ///< 相对强弱指标 (Relative Strength Index)
INDICATOR_MACD, ///< MACD指标
INDICATOR_BOLLINGER, ///< 布林带 (Bollinger Bands)
INDICATOR_STOCHASTIC ///< 随机指标 (KDJ)
};
/**
* @brief 指标管理器类
* @details 封装了系统指标的创建、取值与释放，
* 提供统一的接口管理多个技术指标实例。
* 支持MA、RSI、MACD、布林带等常用指标。
* @ingroup Indicators
*/
class CIndicatorManager
{
private:
int m_handle; ///< @brief 指标句柄
string m_indicator_name; ///< @brief 指标名称
int m_period; ///< @brief 指标周期参数
ENUM_TIMEFRAMES m_timeframe; ///< @brief 指标所在时间周期
/**
* @brief 创建指标句柄（内部方法）
* @param type 指标类型
* @param period 计算周期
* @return true=创建成功，false=创建失败
* @warning 仅在InitIndicator内部调用，外部勿直接使用
*/
bool CreateHandle(ENUM_INDICATOR_TYPE type, int period);
public:
CIndicatorManager();
~CIndicatorManager();
/**
* @brief 初始化指标
* @details 根据指定类型和参数创建指标句柄。
* @param type 指标类型（ENUM_INDICATOR_TYPE）
* @param period 计算周期，默认14
* @param timeframe 时间周期，默认当前周期
* @return true=初始化成功，false=失败
* @note 初始化失败时请检查终端是否有该指标权限
*/
bool InitIndicator(ENUM_INDICATOR_TYPE type,
int period=14,
ENUM_TIMEFRAMES timeframe=PERIOD_CURRENT);
/**
* @brief 获取指标值
* @param shift K线索引（0为当前K线）
* @param buffer 缓冲区索引，默认0（主信号线）
* @return 指标值，失败返回EMPTY_VALUE
*/
double GetValue(int shift, int buffer=0);
/**
* @brief 释放指标句柄
* @details 调用IndicatorRelease释放资源，
* 不再使用时必须调用以避免句柄泄漏。
* @return true=释放成功
*/
bool Release();
/**
* @brief 获取指标名称
* @return 指标名称字符串
*/
string GetName() const { return m_indicator_name; }
};
三、文档生成工具选型：Doxygen vs 自定义脚本 vs Sphinx
在正式动手之前，先花点时间了解一下MQL5文档生成的几种主流方案，以及各自的适用场景。毕竟，工具选对了，事半功倍。
3.1 三种方案横向对比
目前MQL5社区常用的文档生成方案主要有三种：Doxygen（老牌文档生成工具）、Python自定义脚本（自己写解析逻辑）、Sphinx + Breathe（Python生态的文档系统，通过Breathe桥接Doxygen的输出）。
概念：Doxygen对MQL5的支持本质上是"把.mq5文件当作C++来解析"——因为MQL5语法与C++高度相似（类、继承、模板、命名空间均支持），这种映射的准确率可以达到90%以上。MQL5特有的一些关键字（如input、#property等）需要额外处理，但核心的类、函数、变量结构都能被正确识别。
下面从四个维度对比一下三种方案：
| 对比维度 | Doxygen | Python自定义脚本 | Sphinx + Breathe |
|---|---|---|---|
| 上手难度 | 低（配置文件即可） | 中（需写正则解析） | 高（学习成本大） |
| 输出质量 | 高（专业级） | 中（取决于编写水平） | 很高（现代化外观） |
| 可定制性 | 中（CSS + 模板） | 高（完全可控） | 很高（主题生态丰富） |
| 维护成本 | 低（社区活跃） | 高（自己维护） | 中（依赖链较长） |
3.2 不同项目的选型建议
- 个人独立开发者 / 小型项目：推荐Doxygen，配置简单、输出专业，投入产出比最高
- 需要高度定制化输出 / 不想装额外工具：Python脚本是灵活的替代方案，依赖最少
- 大型团队项目 / 需要多语言文档站：可以考虑Sphinx + Breathe，学习成本高但上限也高
本文以Doxygen为主线方案展开，同时在第5章提供一个Python脚本作为补充方案，满足不同技术水平和需求的读者。
四、Doxygen配置MQL5支持——让Doxygen识别.mq5文件
4.1 核心配置思路
Doxygen默认不识别.mq5和.mqh文件，但它提供了灵活的扩展机制，允许我们将自定义扩展名映射到已知的解析器。因为MQL5语法与C++高度相似，所以思路就是：告诉Doxygen，把.mq5和.mqh文件当成C++文件来解析。
风险：Doxygen默认不识别MQL5的input、#property、#property indicator_chart_window等预处理指令，如果不做过滤处理，这些行可能导致解析错误或生成的文档中出现异常内容。建议使用FILTER_PATTERNS配置一个简单的sed过滤器来预处理MQL5特有的语法行。
4.2 完整配置模板
下面是专门适配MQL5的Doxyfile核心配置段。你只需要运行 doxygen -g 生成默认配置文件，然后将以下配置项替换进去即可：
# ============================================================
# Doxyfile 配置模板 - 适配MQL5语言
# 使用方法：运行 doxygen -g 生成默认配置后，替换以下关键项
# ============================================================
# ---------- 项目元信息 ----------
PROJECT_NAME = "我的EA项目"
PROJECT_NUMBER = "1.0.0"
PROJECT_BRIEF = "专业级MQL5 EA - 自动化交易系统"
OUTPUT_DIRECTORY = ./docs
HTML_OUTPUT = html
# ---------- 输入文件配置（MQL5专属） ----------
INPUT = ./src # 你的MQL5源码目录
FILE_PATTERNS = *.mq5 \
*.mqh \
*.cpp \
*.h
# ---------- 扩展名映射（核心！将MQL5映射为C++） ----------
EXTENSION_MAPPING = mq5=C++ \
mqh=C++
# ---------- MQL5语法过滤器（处理特有预处理指令） ----------
# 使用sed过滤MQL5特有的 #property / input / input group 等行
# 注意：Windows下需要安装sed（Git Bash或GOW即可）
FILTER_PATTERNS = *.mq5="sed 's/^input /int MQL5_INPUT_/; s/^#property /\/\* MQL5_PROPERTY: /; s/$/ \*\//'" \
*.mqh="sed 's/^input /int MQL5_INPUT_/; s/^#property /\/\* MQL5_PROPERTY: /; s/$/ \*\//'"
# ---------- 提取范围配置 ----------
EXTRACT_ALL = YES # 提取所有实体，即使没有注释
EXTRACT_PRIVATE = YES # 同时提取私有成员
EXTRACT_STATIC = YES # 提取静态成员
EXTRACT_LOCAL_CLASSES = YES
# ---------- 输出格式配置 ----------
GENERATE_HTML = YES
GENERATE_LATEX = NO # 不需要PDF的话关掉，省时间
GENERATE_TREEVIEW = YES # 左侧树形导航
GENERATE_TESTLIST = NO
GENERATE_BUGLIST = NO
# ---------- 自定义样式入口（第6章会用到） ----------
HTML_HEADER =
HTML_FOOTER =
HTML_EXTRA_STYLESHEET =
# ---------- 搜索功能 ----------
SEARCHENGINE = YES # 启用本地搜索功能
SERVER_BASED_SEARCH = NO
# ---------- 图形化（可选，需要graphviz） ----------
HAVE_DOT = NO # 有graphviz的话设为YES，可生成类图
CALL_GRAPH = NO
CALLER_GRAPH = NO
# Doxyfile 配置模板 - 适配MQL5语言
# 使用方法：运行 doxygen -g 生成默认配置后，替换以下关键项
# ============================================================
# ---------- 项目元信息 ----------
PROJECT_NAME = "我的EA项目"
PROJECT_NUMBER = "1.0.0"
PROJECT_BRIEF = "专业级MQL5 EA - 自动化交易系统"
OUTPUT_DIRECTORY = ./docs
HTML_OUTPUT = html
# ---------- 输入文件配置（MQL5专属） ----------
INPUT = ./src # 你的MQL5源码目录
FILE_PATTERNS = *.mq5 \
*.mqh \
*.cpp \
*.h
# ---------- 扩展名映射（核心！将MQL5映射为C++） ----------
EXTENSION_MAPPING = mq5=C++ \
mqh=C++
# ---------- MQL5语法过滤器（处理特有预处理指令） ----------
# 使用sed过滤MQL5特有的 #property / input / input group 等行
# 注意：Windows下需要安装sed（Git Bash或GOW即可）
FILTER_PATTERNS = *.mq5="sed 's/^input /int MQL5_INPUT_/; s/^#property /\/\* MQL5_PROPERTY: /; s/$/ \*\//'" \
*.mqh="sed 's/^input /int MQL5_INPUT_/; s/^#property /\/\* MQL5_PROPERTY: /; s/$/ \*\//'"
# ---------- 提取范围配置 ----------
EXTRACT_ALL = YES # 提取所有实体，即使没有注释
EXTRACT_PRIVATE = YES # 同时提取私有成员
EXTRACT_STATIC = YES # 提取静态成员
EXTRACT_LOCAL_CLASSES = YES
# ---------- 输出格式配置 ----------
GENERATE_HTML = YES
GENERATE_LATEX = NO # 不需要PDF的话关掉，省时间
GENERATE_TREEVIEW = YES # 左侧树形导航
GENERATE_TESTLIST = NO
GENERATE_BUGLIST = NO
# ---------- 自定义样式入口（第6章会用到） ----------
HTML_HEADER =
HTML_FOOTER =
HTML_EXTRA_STYLESHEET =
# ---------- 搜索功能 ----------
SEARCHENGINE = YES # 启用本地搜索功能
SERVER_BASED_SEARCH = NO
# ---------- 图形化（可选，需要graphviz） ----------
HAVE_DOT = NO # 有graphviz的话设为YES，可生成类图
CALL_GRAPH = NO
CALLER_GRAPH = NO
配置完成后，在命令行运行 doxygen Doxyfile，等待几秒到几十秒（取决于项目大小），就能在 docs/html/ 目录下找到生成的HTML文档了。
五、实战：从一个EA项目生成完整API文档
5.1 项目准备
我们以一个包含 CIndicatorManager 类的EA项目为例，从零开始配置Doxygen并生成文档。假设项目目录结构如下：
MyEAProject/
├── src/
│ ├── MyEA.mq5 # EA主程序
│ ├── CIndicatorManager.mqh # 指标管理类
│ ├── CRiskManager.mqh # 风控管理类
│ └── CTradeManager.mqh # 交易管理类
├── docs/ # 文档输出目录
└── Doxyfile # Doxygen配置文件
├── src/
│ ├── MyEA.mq5 # EA主程序
│ ├── CIndicatorManager.mqh # 指标管理类
│ ├── CRiskManager.mqh # 风控管理类
│ └── CTradeManager.mqh # 交易管理类
├── docs/ # 文档输出目录
└── Doxyfile # Doxygen配置文件
5.2 生成步骤详解
- 生成默认配置：在项目根目录运行
doxygen -g，自动生成Doxyfile - 修改关键配置：按照上一章的配置模板，修改PROJECT_NAME、INPUT、FILE_PATTERNS、EXTENSION_MAPPING等核心配置项
- 运行生成：执行
doxygen Doxyfile，观察输出日志，确认没有报错 - 查看结果：打开 docs/html/index.html，就是生成的文档首页
风险：如果某个类或函数没出现在文档里，90%的情况是它上面没有Doxygen格式的注释块——必须以/**开头而不是/*。普通的 /* 注释Doxygen是不会提取的，一定要注意开头是两个星号。另外，如果EXTRACT_ALL设为NO，那么没有注释的实体会被忽略。
5.3 生成结果解读
生成的文档通常包含以下几个主要页面：
- 首页（Main Page）：项目简介、版本信息等，可以用 @mainpage 标签自定义内容
- 类列表（Classes）：所有类的列表，点击进入查看类的成员函数、成员变量
- 文件列表（Files）：所有源文件的列表，按文件维度查看文档
- 函数列表（Functions）：所有函数的索引，便于搜索
- 搜索框：如果启用了SEARCHENGINE，可以在文档站内搜索
技巧：使用
doxygen -w html header.html footer.html custom.css 命令可以一键导出Doxygen的默认HTML模板，在此基础上修改比从零开始写快得多。这个命令会把当前配置对应的头模板、尾模板和CSS都导出来，你改完再配置回HTML_HEADER等选项就行。
5.4 补充方案：Python轻量文档生成脚本
如果你不想安装Doxygen，或者需要高度定制化的文档格式，可以使用Python脚本自己解析MQL5代码。下面是一个轻量级的Python脚本，使用正则表达式提取类、函数、枚举和注释，生成单页HTML文档：
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""
MQL5 轻量文档生成脚本
功能：解析.mq5/.mqh文件中的Doxygen风格注释，生成单页HTML文档
依赖：仅Python标准库（re, os, datetime）
用法：python mql5_docs_generator.py <源码目录> <输出HTML路径>
"""
import re
import os
import sys
import datetime
# ---------- 正则表达式定义 ----------
# 匹配Doxygen块注释 /** ... */
DOC_COMMENT_PATTERN = re.compile(r'/\*\*\s*(.*?)\s*\*/', re.DOTALL)
# 匹配 class 定义
CLASS_PATTERN = re.compile(
r'class\s+(\w+)\s*[:{]',
re.MULTILINE
)
# 匹配 enum 定义
ENUM_PATTERN = re.compile(
r'enum\s+(\w+)\s*\{',
re.MULTILINE
)
# 匹配函数定义（简化版，匹配返回类型 + 函数名 + 参数列表）
FUNCTION_PATTERN = re.compile(
r'^\s*(?:void|bool|int|double|string|datetime|color|uchar|short|long|
\w+)\s+(\w+)\s*\((.*?)\)\s*(?:const)?\s*(?:;|override)?\s*$',
re.MULTILINE
)
# ---------- 标签提取函数 ----------
def extract_tags(doc_text):
"""从注释文本中提取 @brief, @param, @return 等标签"""
tags = {'brief': '', 'params': [], 'return': '', 'note': '', 'warning': ''}
# 提取@brief
brief_match = re.search(r'@brief\s+(.+?)(?= \s*@| \s*\*/|$)', doc_text, re.DOTALL)
if brief_match:
tags['brief'] = brief_match.group(1).strip()
# 提取所有@param
for param_match in re.finditer(r'@param\[(in|out|in,out)\]\s+(\w+)\s+(.+?)(?= \s*@| \s*\*/|$)', doc_text, re.DOTALL):
direction = param_match.group(1)
name = param_match.group(2)
desc = param_match.group(3).strip()
tags['params'].append({'name': name, 'direction': direction, 'desc': desc})
# 提取@return
return_match = re.search(r'@return\s+(.+?)(?= \s*@| \s*\*/|$)', doc_text, re.DOTALL)
if return_match:
tags['return'] = return_match.group(1).strip()
return tags
# ---------- 主解析函数 ----------
def parse_mql5_file(filepath):
"""解析单个MQL5文件，提取类、枚举、函数信息"""
with open(filepath, 'r', encoding='utf-8', errors='ignore') as f:
content = f.read()
result = {'file': os.path.basename(filepath), 'classes': [], 'enums': [], 'functions': []}
# 查找所有文档注释块及其位置
doc_blocks = [(m.start(), m.end(), m.group(1)) for m in DOC_COMMENT_PATTERN.finditer(content)]
# 匹配类
for cls_match in CLASS_PATTERN.finditer(content):
cls_name = cls_match.group(1)
cls_pos = cls_match.start()
# 找最近的前置注释
preceding_doc = ''
for start, end, text in reversed(doc_blocks):
if end < cls_pos and cls_pos - end < 200:
preceding_doc = text
break
result['classes'].append({'name': cls_name, 'doc': extract_tags(preceding_doc)})
# 匹配枚举
for enum_match in ENUM_PATTERN.finditer(content):
enum_name = enum_match.group(1)
result['enums'].append({'name': enum_name})
return result
# ---------- HTML生成函数 ----------
def generate_html(docs, title="MQL5 API文档"):
"""根据解析结果生成HTML字符串"""
now = datetime.datetime.now().strftime("%Y-%m-%d %H:%M:%S")
html_parts =
for doc in docs:
html_parts.append(f'
for cls in doc['classes']:
html_parts.append(f'
')
for enum in doc['enums']:
html_parts.append(f'')
html_parts.append(f"""
# -*- coding: utf-8 -*-
"""
MQL5 轻量文档生成脚本
功能：解析.mq5/.mqh文件中的Doxygen风格注释，生成单页HTML文档
依赖：仅Python标准库（re, os, datetime）
用法：python mql5_docs_generator.py <源码目录> <输出HTML路径>
"""
import re
import os
import sys
import datetime
# ---------- 正则表达式定义 ----------
# 匹配Doxygen块注释 /** ... */
DOC_COMMENT_PATTERN = re.compile(r'/\*\*\s*(.*?)\s*\*/', re.DOTALL)
# 匹配 class 定义
CLASS_PATTERN = re.compile(
r'class\s+(\w+)\s*[:{]',
re.MULTILINE
)
# 匹配 enum 定义
ENUM_PATTERN = re.compile(
r'enum\s+(\w+)\s*\{',
re.MULTILINE
)
# 匹配函数定义（简化版，匹配返回类型 + 函数名 + 参数列表）
FUNCTION_PATTERN = re.compile(
r'^\s*(?:void|bool|int|double|string|datetime|color|uchar|short|long|
\w+)\s+(\w+)\s*\((.*?)\)\s*(?:const)?\s*(?:;|override)?\s*$',
re.MULTILINE
)
# ---------- 标签提取函数 ----------
def extract_tags(doc_text):
"""从注释文本中提取 @brief, @param, @return 等标签"""
tags = {'brief': '', 'params': [], 'return': '', 'note': '', 'warning': ''}
# 提取@brief
brief_match = re.search(r'@brief\s+(.+?)(?= \s*@| \s*\*/|$)', doc_text, re.DOTALL)
if brief_match:
tags['brief'] = brief_match.group(1).strip()
# 提取所有@param
for param_match in re.finditer(r'@param\[(in|out|in,out)\]\s+(\w+)\s+(.+?)(?= \s*@| \s*\*/|$)', doc_text, re.DOTALL):
direction = param_match.group(1)
name = param_match.group(2)
desc = param_match.group(3).strip()
tags['params'].append({'name': name, 'direction': direction, 'desc': desc})
# 提取@return
return_match = re.search(r'@return\s+(.+?)(?= \s*@| \s*\*/|$)', doc_text, re.DOTALL)
if return_match:
tags['return'] = return_match.group(1).strip()
return tags
# ---------- 主解析函数 ----------
def parse_mql5_file(filepath):
"""解析单个MQL5文件，提取类、枚举、函数信息"""
with open(filepath, 'r', encoding='utf-8', errors='ignore') as f:
content = f.read()
result = {'file': os.path.basename(filepath), 'classes': [], 'enums': [], 'functions': []}
# 查找所有文档注释块及其位置
doc_blocks = [(m.start(), m.end(), m.group(1)) for m in DOC_COMMENT_PATTERN.finditer(content)]
# 匹配类
for cls_match in CLASS_PATTERN.finditer(content):
cls_name = cls_match.group(1)
cls_pos = cls_match.start()
# 找最近的前置注释
preceding_doc = ''
for start, end, text in reversed(doc_blocks):
if end < cls_pos and cls_pos - end < 200:
preceding_doc = text
break
result['classes'].append({'name': cls_name, 'doc': extract_tags(preceding_doc)})
# 匹配枚举
for enum_match in ENUM_PATTERN.finditer(content):
enum_name = enum_match.group(1)
result['enums'].append({'name': enum_name})
return result
# ---------- HTML生成函数 ----------
def generate_html(docs, title="MQL5 API文档"):
"""根据解析结果生成HTML字符串"""
now = datetime.datetime.now().strftime("%Y-%m-%d %H:%M:%S")
html_parts =
for doc in docs:
html_parts.append(f'
文件：{doc["file"]}
')for cls in doc['classes']:
html_parts.append(f'
类：{cls["name"]}
{cls["doc"]["brief"] or "（暂无简介）"}
')
for enum in doc['enums']:
html_parts.append(f'
枚举：{enum["name"]}
html_parts.append(f"""