docs: explain match assertions and annotation type distinctions

crates/frontend/tests/ast.rs

@@ -26,6 +26,7 @@ fn function_bodies_accept_method_statements_and_optional_trailing_return() {
             .body
             .statements
             .iter()
+            // 两个调用都应是普通 Expression 语句，不能被误识别为返回或绑定。
             .all(|s| matches!(s.kind, StmtKind::Expression(_)))
     );
     assert!(parse_ast("function empty(): Unit {}", ParseMode::Module).is_ok());
@@ -258,6 +259,7 @@ fn json_interfaces_reject_unknown_fields_schema_changes_and_invalid_ranges() {
         kind: ExprKind::Name("値".into()),
         span: Span::new(1, 3),
     });
+    // 结构范围虽非逆序，起点切断三字节日文字符，仍须在提供原文的校验阶段失败。
     assert!(matches!(
         AstDocument::new(root).unwrap().validate_source("値"),
         Err(AstError::InvalidSpan(_))

crates/frontend/tests/reader.rs

@@ -291,6 +291,7 @@ fn uri_snapshots_require_a_revision_and_preserve_it_in_source_diagnostics() {
         revision: " \t",
         bytes: b"1",
     };
+    // 字节有效不能补救缺版本身份，空白版本标签应单独报告 MissingRevision。
     assert!(matches!(
         EndorReader::from_endor(uri, &missing).unwrap_err().kind,
         SourceReadErrorKind::MissingRevision
@@ -336,6 +337,7 @@ fn invalid_uris_do_not_call_the_provider_and_denials_do_not_fall_back_to_files()
         "endor:space here",
         "endor:bad\nname",
     ] {
+        // 每个非法定位符都必须先被基础 URI 校验拒绝，后面的计数零验证未访问宿主。
         assert!(matches!(
             EndorReader::from_endor(uri, &provider).unwrap_err().kind,
             SourceReadErrorKind::InvalidEndorUri

crates/frontend/tests/syntax.rs

@@ -190,6 +190,7 @@ fn arithmetic_precedence_and_left_associativity_form_the_expected_tree() {
     let ExprKind::Unary { operand, .. } = nested.kind else {
         panic!("expected outer negate");
     };
+    // 外层负号的操作数仍是 Negate，证明解析器保留两个前缀节点而未提前计算数值。
     assert!(matches!(
         operand.kind,
         ExprKind::Unary {