internal: docs

crates/hir_def/src/macro_expansion_tests/mbe.rs

@@ -1,3 +1,6 @@
+//! Tests specific to declarative macros, aka macros by example. This covers
+//! both stable `macro_rules!` macros as well as unstable `macro` macros.
+
 mod tt_conversion;
 mod matching;
 mod meta_syntax;
@@ -25,3 +28,21 @@ fn f() { let _ = /* error: could not convert tokens */; }
 "#]],
     )
 }
+
+#[test]
+fn wrong_nesting_level() {
+    check(
+        r#"
+macro_rules! m {
+    ($($i:ident);*) => ($i)
+}
+m!{a}
+"#,
+        expect![[r#"
+macro_rules! m {
+    ($($i:ident);*) => ($i)
+}
+/* error: expected simple binding, found nested binding `i` */
+"#]],
+    );
+}

crates/hir_def/src/macro_expansion_tests/mbe/matching.rs

@@ -1,3 +1,5 @@
+//! Test that `$var:expr` captures function correctly.
+
 use expect_test::expect;
 
 use crate::macro_expansion_tests::check;
@@ -21,21 +23,3 @@ literal!()
 "#]],
     )
 }
-
-#[test]
-fn wrong_nesting_level() {
-    check(
-        r#"
-macro_rules! m {
-    ($($i:ident);*) => ($i)
-}
-m!{a}
-"#,
-        expect![[r#"
-macro_rules! m {
-    ($($i:ident);*) => ($i)
-}
-/* error: expected simple binding, found nested binding `i` */
-"#]],
-    );
-}

crates/hir_def/src/macro_expansion_tests/mbe/meta_syntax.rs

@@ -1,3 +1,5 @@
+//! Test for the syntax of macros themselves.
+
 use expect_test::expect;
 
 use crate::macro_expansion_tests::check;

crates/hir_def/src/macro_expansion_tests/mbe/tt_conversion.rs

@@ -1,3 +1,8 @@
+//! Unlike rustc, rust-analyzer's syntax tree are not "made of" token trees.
+//! Rather, token trees are an explicit bridge between the parser and
+//! (procedural or declarative) macros.
+//!
+//! This module tests tt <-> syntax tree conversion specifically
 use expect_test::expect;
 
 use crate::macro_expansion_tests::check;