compiler 模块注释完善：Doxygen 风格（Lexer/Parser/Linker/Typecheck/Project/MachineConfig/TypeInfo/Codec/Codegen/Stb/main 共 21 个文件）

compiler/src/MachineConfig.cpp

@@ -22,6 +22,10 @@
 
 namespace compiler {
 
+/**
+ * @brief 内建基元表。
+ * @return 静态基元表（bit / int8..uint64 / float32 / float64，元数据在代码）
+ */
 const std::vector<PrimType>& MachineConfig::prims() {
     static const std::vector<PrimType> kPrims = {
         {"bit", 1, false, false},
@@ -39,6 +43,11 @@ const std::vector<PrimType>& MachineConfig::prims() {
     return kPrims;
 }
 
+/**
+ * @brief 按名称查内建基元。
+ * @param name 基元名
+ * @return 命中指针；未找到返回 nullptr
+ */
 const PrimType* MachineConfig::find_prim(const std::string& name) {
     for (const PrimType& p : prims()) {
         if (p.name == name) {
@@ -50,7 +59,12 @@ const PrimType* MachineConfig::find_prim(const std::string& name) {
 
 namespace {
 
-    // 稳定前缀
+    /**
+     * @brief 写错误信息（稳定前缀 "machine error"）并原样返回 msg。
+     * @param err 错误输出；可为 nullptr（静默）
+     * @param msg 错误描述
+     * @return msg（供调用方直接 return）
+     */
     std::string fail(std::string* err, const std::string& msg) {
         if (err) {
             *err = "machine error: " + msg;
@@ -58,7 +72,11 @@ namespace {
         return msg;
     }
 
-    // format → 参数数量（解析时校验）
+    /**
+     * @brief format → 期望参数数量（解析时校验）。
+     * @param format 操作数形态（RR/RRR/IMM/SLOT/JMP/JC/CALL/CAL/NONE）
+     * @return 参数数量；未知 format 返回 -1
+     */
     int params_of(const std::string& format) {
         if (format == "RR") return 2;
         if (format == "RRR") return 3;
@@ -72,15 +90,25 @@ namespace {
         return -1;
     }
 
+    /// @brief format 是否已知（params_of 返回非负）。
     bool is_known_format(const std::string& f) {
         return params_of(f) >= 0;
     }
 
+    /// @brief tag 是否在 .stb 常量表契约内（0=BOOL、1=INT、2=TIME）。
     bool is_known_tag(uint32_t tag) {
         return tag <= 2;  // .stb 常量表契约：0=BOOL 1=INT 2=TIME
     }
 
-    // 必填字符串
+    /**
+     * @brief 读必填字符串字段。
+     * @param t 配置表
+     * @param what 表归属描述（用于错误信息，如 "[meta]"）
+     * @param key 字段名
+     * @param out 输出值
+     * @param err 错误输出；可为 nullptr（静默）
+     * @return true 成功；false（字段缺失或类型不符，err 已写 "machine error: ..."）
+     */
     bool req_string(const toml::table& t, const char* what, const std::string& key,
                     std::string* out, std::string* err) {
         const auto nv = t[key];
@@ -92,7 +120,15 @@ namespace {
         return true;
     }
 
-    // 必填整数
+    /**
+     * @brief 读必填整数字段。
+     * @param t 配置表
+     * @param what 表归属描述（用于错误信息，如 "[meta]"）
+     * @param key 字段名
+     * @param out 输出值
+     * @param err 错误输出；可为 nullptr（静默）
+     * @return true 成功；false（字段缺失或类型不符，err 已写 "machine error: ..."）
+     */
     bool req_int(const toml::table& t, const char* what, const std::string& key,
                  int64_t* out, std::string* err) {
         const auto nv = t[key];
@@ -104,7 +140,15 @@ namespace {
         return true;
     }
 
-    // 必填布尔
+    /**
+     * @brief 读必填布尔字段。
+     * @param t 配置表
+     * @param what 表归属描述（用于错误信息，如 "[meta]"）
+     * @param key 字段名
+     * @param out 输出值
+     * @param err 错误输出；可为 nullptr（静默）
+     * @return true 成功；false（字段缺失或类型不符，err 已写 "machine error: ..."）
+     */
     bool req_bool(const toml::table& t, const char* what, const std::string& key,
                   bool* out, std::string* err) {
         const auto nv = t[key];
@@ -118,6 +162,19 @@ namespace {
 
 }  // namespace
 
+/**
+ * @brief 加载 machine.toml 并做强校验。
+ * @param path machine.toml 路径
+ * @param err 错误输出；可为 nullptr（静默）
+ * @return true 成功；false（err 已写，前缀 "machine error"）
+ * @details 校验顺序与文件头清单 1~5 一致：
+ *          1. TOML 语法与字段完整性（meta/type/op/fb 全属性必填）
+ *          2. type.base 命中内建基元；range 合法（min ≤ max）
+ *          3. tag 与 .stb 常量表契约一致（BOOL=0、INT=1、TIME=2，唯一）
+ *          4. op.opcode 唯一、0..255；class/format 合法；类别-格式互锁（INSTANCE ↔ CAL）；
+ *             params 数量与 format 一致
+ *          5. fb.opcode 与 op 行（instance 类）一致；字段类型命中配置类型表；字段名唯一
+ */
 bool MachineConfig::load(const std::string& path, std::string* err) {
     ok_ = false;
     model_name_.clear();
@@ -352,6 +409,11 @@ bool MachineConfig::load(const std::string& path, std::string* err) {
     return true;
 }
 
+/**
+ * @brief 按配置类型名查类型行。
+ * @param name 配置类型名
+ * @return 命中指针；未找到返回 nullptr
+ */
 const ConfigType* MachineConfig::find_type(const std::string& name) const {
     for (const ConfigType& t : types_) {
         if (t.name == name) {
@@ -361,6 +423,11 @@ const ConfigType* MachineConfig::find_type(const std::string& name) const {
     return nullptr;
 }
 
+/**
+ * @brief 按助记符查指令行。
+ * @param name 助记符（如 "MOVE"）
+ * @return 命中指针；未找到返回 nullptr
+ */
 const ConfigOp* MachineConfig::find_op(const std::string& name) const {
     for (const ConfigOp& o : ops_) {
         if (o.name == name) {
@@ -370,6 +437,11 @@ const ConfigOp* MachineConfig::find_op(const std::string& name) const {
     return nullptr;
 }
 
+/**
+ * @brief 按 opcode 查指令行。
+ * @param opcode 操作码（0..255）
+ * @return 命中指针；未找到返回 nullptr
+ */
 const ConfigOp* MachineConfig::find_op_by_code(uint32_t opcode) const {
     for (const ConfigOp& o : ops_) {
         if (o.opcode == opcode) {
@@ -379,11 +451,21 @@ const ConfigOp* MachineConfig::find_op_by_code(uint32_t opcode) const {
     return nullptr;
 }
 
+/**
+ * @brief 查询某 opcode 是否启用。
+ * @param opcode 操作码
+ * @return 指令存在且 enabled 为 true；未知 opcode 返回 false
+ */
 bool MachineConfig::op_enabled(uint32_t opcode) const {
     const ConfigOp* op = find_op_by_code(opcode);
     return op != nullptr && op->enabled;
 }
 
+/**
+ * @brief 按名称查内建 FB。
+ * @param name FB 名（小写，如 "ton"）
+ * @return 命中指针；未找到返回 nullptr
+ */
 const ConfigFb* MachineConfig::find_fb(const std::string& name) const {
     for (const ConfigFb& f : fbs_) {
         if (f.name == name) {