internal: docs

4 files changed, 30 insertions, 18 deletions

diff --git a/crates/hir_def/src/macro_expansion_tests/mbe.rs b/crates/hir_def/src/macro_expansion_tests/mbe.rs
index 50499840a3a..cc6551f8aa6 100644
--- a/crates/hir_def/src/macro_expansion_tests/mbe.rs
+++ b/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` */
+"#]],
+    );
+}
diff --git a/crates/hir_def/src/macro_expansion_tests/mbe/matching.rs b/crates/hir_def/src/macro_expansion_tests/mbe/matching.rs
index cfba58c55a4..11317cfa9d5 100644
--- a/crates/hir_def/src/macro_expansion_tests/mbe/matching.rs
+++ b/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` */
-"#]],
-    );
-}
diff --git a/crates/hir_def/src/macro_expansion_tests/mbe/meta_syntax.rs b/crates/hir_def/src/macro_expansion_tests/mbe/meta_syntax.rs
index 1c4bb9d7b84..4249c2507e9 100644
--- a/crates/hir_def/src/macro_expansion_tests/mbe/meta_syntax.rs
+++ b/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;
diff --git a/crates/hir_def/src/macro_expansion_tests/mbe/tt_conversion.rs b/crates/hir_def/src/macro_expansion_tests/mbe/tt_conversion.rs
index d445d7a2c61..a24fe9bee2c 100644
--- a/crates/hir_def/src/macro_expansion_tests/mbe/tt_conversion.rs
+++ b/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;