topic5: docs

[SCOFRD]

No description provided.

[github-actions]

🤖 AI Code Review

共审查 2 个变更文件

📁 docs/topic5汇编代码美化器开发文档.md

🔴 内部引用不一致 — 验收标准中提及“与设计文档第 2.2 节一致”和“与设计文档第 2.4 节一致”，但本文档第 2.2 节为关键算法/流程，未包含段标题映射；第 2.4 节不存在。需补充或修正引用，避免实现歧义。

🟡 BNF 缺失字符串字面量定义 — 输入语法基准未定义字符串字面量（如 "hello, world"），但操作数拆分要求感知字符串内的逗号和 #。需明确字符串语法（双引号/单引号、转义规则），否则解析器实现可能遗漏边界情况。

🟡 未定义数据定义指令集合 — 多处提到“数据定义行不生成运行时指令注释”，但未列出哪些指令被视为数据定义（如 .byte, .word, .string, .align 等）。需明确集合，否则实现无法判断是否禁用注释。

🟡 操作数拆分未覆盖字符串内逗号 — 规则强调“顶层逗号拆分，括号内逗号不拆分”，但未提及字符串字面量内的逗号（如 .string "a,b" 中的逗号不应作为分隔符）。需补充字符串上下文处理策略。

💭 对齐宽度对应关系不明确 — “三列填充宽度按 min(实际最大长度, 30/12/40) 计算”，未说明 30/12/40 分别对应 label/opcode/operands_str。建议明确写为 label: min(…, 30), opcode: min(…, 12), operands_str: min(…, 40)。

💭 注释关键字拼写 — 异常状态注释中使用 [warning: malformed instruction]，英文应为 malformed（畸形）而非 malformed。建议修正拼写，或统一使用项目约定词。

💭 metadata_label BNF 中 number 未定义 — _op_PPQ_Operation_ number _ number 中的 number 未给出词法规则，建议定义为 digit { digit } 避免实现不一致。

💭 beautify_file() 的 encoding 参数未在描述中突出 — 函数签名包含 encoding，但文档描述只提到 align、add_comments、abi_register_names，建议补全或说明默认编码。

---

📁 docs/topic5汇编代码美化器设计文档.md

🟡 模糊的函数入口识别规则 — 第2.4节第5条要求“仅作为分支目标出现的普通标签”不生成函数标题，但未给出如何判断“仅作为分支目标”的具体方法（需要完整静态分析）。建议改用更简单的启发式（如仅依赖 .globl/.type 声明或标签名称模式），或明确说明实现将跳过此规则以避免复杂性。

🟡 数据段字符串中 # 的处理条件不明确 — 第2.5节说“无法可靠分离字符串与注释的行标记为 malformed”，但未定义“无法可靠分离”的判定条件。建议明确：当字符串内出现 # 且未闭合时，或引号状态无法正确跟踪时，才标记为 malformed。

🟡 列宽扫描阶段使用的字符串不明确 — 第4.4节说“规范化后操作数字符串”用于统计长度，但第4.3节中的 operands_str 是原始字符串。建议明确扫描阶段使用原始 operands_str 还是经过空格规范化后的字符串，以保证实现一致性。

🟡 ABI 别名转换中内存操作数基址寄存器的提取未说明 — 第4.5节提到“从内存寻址表达式中提取出的基址寄存器”应转换，但未给出提取方法（如 28(sp) 中的 sp 或 28(x2) 中的 x2）。建议增加简要解析规则或说明由专用解析器提供基址寄存器字段。

💭 2.5节与2.6节对异常行注释的描述措辞不一致 — 2.5节说“自动注释只输出对应的警告信息”，2.6节说警告替代自动注释并与原始注释合并。建议统一为“警告注释替代自动语义注释，若已有用户注释则以 | 合并”。

💭 段标题重复插入的“紧邻”判定未定义 — 第2.2节说“对已经紧邻同类标题的 directive 不重复插入”，但未说明“紧邻”是否允许空行或注释间隔。建议明确：若上一个同类标题与当前 directive 之间仅存在空白行或注释行，仍视为紧邻。

💭 命令行选项默认值未显式说明 — 第2.7节中 --no-align 等开关的默认行为只能从上下文推断。建议增加一句“默认情况下对齐和注释均开启”。

💭 超长字段时注释列对齐行为未规定 — 第2.2节说超长字段后“其后字段自然右移”，但未提注释列是否也右移。建议明确注释列同样跟随超长字段自然右移，或保持固定列位置。

💭 文档版本日期为2026年，疑似笔误 — 建议核对并修正为实际日期。

---