神经网络变得轻松（第九部分）：操作归档（基础篇）
◍ 给 MQL5 代码做技术归档的底层逻辑
在 MT5 里写复杂 EA 或指标时，源码很快会膨胀到几百行，没有归档习惯的人三个月后自己都看不懂。文章作者 Dmitriy Gizlyk 在 2021 年 3 月 16 日发布的系列第九篇中，专门讲操作归档：核心原则是在写代码的同时就留下结构化文档，而不是完工后再补。 他列了五个实操阶段：创建文档基本原则、选工具、在代码里归档、源码文件预处理、最后生成文档。整个流程跑通后，用 MetaEditor 打开任意函数都能直接看到参数说明和用途，省掉反复翻聊天记录问自己的成本。 外汇和贵金属策略迭代快、回测窗口短，这类归档能降低多人协作或隔周复盘的出错概率。高风险品种下，一处注释错位可能让仓位逻辑反向，文档化不是整洁癖，是风控的一部分。
代码膨胀后为什么需要文档化视角
前几篇里我们不断往函数库塞新对象、扩旧方法，还引入了 OpenCL 程序文件，现在代码体量已经是初版的 10 倍以上。对象间调用关系肉眼跟不住，读者反馈读起来像一团乱麻，单篇拆动作链解决不了全局理解。 光靠每篇文章讲局部逻辑，没法看清谁继承谁、谁调谁。所以我打算演示怎么给这套库生成代码文档，把全部对象和方法摊开，顺手建出继承层次。换个角度扫一遍，你大概就知道这套东西全貌长什么样了。
「写文档前先想清楚给谁看」
技术文档在 IT 开发里第一职责是给程序体系结构和操作画全貌。团队靠它切分责任边界、追代码改动、评估某次提交对算法完整性的冲击，同时也能把架构知识在成员间传开。 写之前得先锚定读者资质：信息要清晰，别堆过量解释。该给的给全，但篇幅压住——冗长文档不仅耗阅读时间，真找不到重点时用户反感更强。这引出一条硬要求：文档得带便捷检索，交叉引用和友好界面能直接降低定位成本。 文档要覆盖完整解决方案架构和已落地的技术实现说明，且必须随时保持更新。过时描述会诱发管理决策冲突，进而让整体开发节奏失衡；组件间接口也得写明白，否则后续支持根本无从下手。
◍ 给 MQL5 挑文档生成器
写代码注释谁都不爱干，但后期查函数、交接策略时没文档就是灾难。社区里能自动出文档的专用工具不少，Doxygen、Sphinx、Latex 是三类典型，它们本意都是压低手工写说明的成本。 Doxygen 起初面向 C++，Sphinx 为 Python 而生，但二者都能跨语言跑。MQL5 语法贴近 C++，所以前文《自动创建 MQL5 程序的文档》和我自己的开发都直接选了 Doxygen。 它的关键好处只有一个：你只在源码里加标准注释，剩下的提取、排版、生成全交给软件。更实用的是 Doxygen 支持插超链接和数学公式——做价格行为指标文档时，公式能原样渲染，这点对量化交易者很关键。 本文后续会用具体示例拆 Doxygen 在 MQL5 里的实际用法，你可以现在开 MT5 建个空 EA，先按 /** 注释 */ 写两个函数试试生成。
把注释喂给文档生成器
给 MQL5 程序写文档，不是把所有代码注释都倒进文档里。开发过程中的私人批注、废弃代码说明，理应被过滤掉。Doxygen 用特定标记区分「要进文档的注释」和「仅给自己看的注释」，这套标记规则你得先定下来，否则日后直接抽取代码时会一团乱。
最省事的做法是沿用类 MQL5 风格：单行文档注释多加一个斜杠变成 ///，多行块尾加星号变成 /** ... */；若嫌不够醒目，也可用 //! 和 /*! ... */ 作替代标记。实测中这两种写法 MT5 编译器都不报错，但只有前者在多数自动文档模板里零配置识别。
文档块不强制和输出排版一一对应。同一对象想分「简述 / 详述」，要么写两个相邻块，要么用 \brief、\details 这类反斜杠命令，或用 @ 等价写法；\n 能强制换行。若对象定义在注释块前面，要在块内加 < 告诉解析器「注释的是前一行」；交叉引用其他类则在名字前加 #，例如 #CConnection 会链到对应类页面。
下面这段可直接贴进 MQ5 文件顶部试解析：
/// A single-line comment for documentation
/** A multi-line block for documentation
*/
//! An alternative single-line comment for documentation
/*! An alternative
multi-line
block for
documentation
*/
选项 1: 分离的块
/// Short description
/** Detailed description
*/
选项 2: 特殊命令的用法
/** \brief Brief description
\details Detailed description
*/
#define defConnect 0x7781 ///<Connection \details Identified class #CConnection
Doxygen 完整命令表在其文档板块可查，它还认 HTML / XML 标签。写 EA 或指标库时，提前用对注释标记，能让小布类工具直接抽结构，省掉手工维护说明的高频麻烦。
class=class="str">"cmt">/// A single-line comment for documentation class=class="str">"cmt">/** A multi-line block for documentation */ class=class="str">"cmt">//! An alternative single-line comment for documentation class=class="str">"cmt">/*! An alternative multi-line block for documentation */ 选项 class="num">1: 分离的块 class=class="str">"cmt">/// Short description class=class="str">"cmt">/** Detailed description */ 选项 class="num">2: 特殊命令的用法 class=class="str">"cmt">/** \brief Brief description \details Detailed description */ class="macro">#define defConnect 0x7781 class=class="str">"cmt">///<Connection \details Identified class class="macro">#CConnection