From 84d182c7a2002cd6e511db341ddddcd8ba473105 Mon Sep 17 00:00:00 2001
From: Aleksey Kladov <aleksey.kladov@gmail.com>
Date: Sat, 9 Oct 2021 15:29:31 +0300
Subject: [PATCH] internal: docs

---
 .../hir_def/src/macro_expansion_tests/mbe.rs  | 21 +++++++++++++++++++
 .../src/macro_expansion_tests/mbe/matching.rs | 20 ++----------------
 .../macro_expansion_tests/mbe/meta_syntax.rs  |  2 ++
 .../mbe/tt_conversion.rs                      |  5 +++++
 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 50499840a3..cc6551f8aa 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 cfba58c55a..11317cfa9d 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 1c4bb9d7b8..4249c2507e 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 d445d7a2c6..a24fe9bee2 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;