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

compiler/src/Codec.cpp

@@ -3,6 +3,9 @@
  * @brief 指令字编解码 + 配置驱动反汇编（编译器侧）
  * @author 
  * @date 2026-08-21
+ *
+ * @details pack / op_of / imm16_of / off16_of 与执行器 isa 字节布局一致；
+ *          disasm 由 MachineConfig 驱动（opcode 名 / format / 参数名来自配置）。
  */
 
 #include "compiler/Codec.h"
@@ -11,6 +14,14 @@
 
 namespace compiler {
 
+/**
+ * @brief 打包：四个字段拼成一条指令字。
+ * @param opcode 操作码（低 8 位）
+ * @param rd 目标寄存器 / 条件寄存器（第 8..15 位）
+ * @param a 源寄存器 / 立即数低 8 位 / 偏移低 8 位（第 16..23 位）
+ * @param b 源寄存器 / 立即数高 8 位 / 偏移高 8 位（第 24..31 位）
+ * @return 打包后的指令字（小端 u32）
+ */
 Instr pack(uint8_t opcode, uint8_t rd, uint8_t a, uint8_t b) {
     return static_cast<uint32_t>(opcode)
         | (static_cast<uint32_t>(rd) << 8)
@@ -18,17 +29,40 @@ Instr pack(uint8_t opcode, uint8_t rd, uint8_t a, uint8_t b) {
         | (static_cast<uint32_t>(b) << 24);
 }
 
+/// @brief 取操作码（低 8 位）。
 uint8_t op_of(Instr w) { return static_cast<uint8_t>(w & 0xFFu); }
+/// @brief 取 rd 字段（第 8..15 位）。
 uint8_t rd_of(Instr w) { return static_cast<uint8_t>((w >> 8) & 0xFFu); }
+/// @brief 取 a 字段（第 16..23 位）。
 uint8_t a_of(Instr w) { return static_cast<uint8_t>((w >> 16) & 0xFFu); }
+/// @brief 取 b 字段（第 24..31 位）。
 uint8_t b_of(Instr w) { return static_cast<uint8_t>((w >> 24) & 0xFFu); }
 
+/**
+ * @brief a|b 拼成 16 位无符号数。
+ * @param w 指令字
+ * @return 小端拼出的 16 位值（const_id / slot / fn_id）
+ */
 uint16_t imm16_of(Instr w) {
     return static_cast<uint16_t>(a_of(w) | (static_cast<uint16_t>(b_of(w)) << 8));
 }
 
+/**
+ * @brief a|b 为有符号相对偏移。
+ * @param w 指令字
+ * @return 偏移量（单位：指令条数，相对下一条指令）
+ */
 int16_t off16_of(Instr w) { return static_cast<int16_t>(imm16_of(w)); }
 
+/**
+ * @brief 配置驱动反汇编：按 machine.toml 的 format 输出一行文本。
+ * @param cfg 机器配置（opcode 名 / format / 参数名来源）
+ * @param w 指令字
+ * @param out 输出缓冲
+ * @param cap 缓冲容量（含 '\0'）；cap==0 时直接返回、不写 out
+ * @details 未知操作码输出 `??? 0x%08x`；format 分支 RR/RRR/IMM/SLOT/JMP/JC/CALL/CAL/NONE
+ *          输出文本与 Doc/isa/指令与映像.md 一致。
+ */
 void disasm(const MachineConfig& cfg, Instr w, char* out, size_t cap) {
     if (cap == 0) {
         return;