Update `DefMap` and `block_def_map` docs

2 files changed, 25 insertions, 1 deletions

diff --git a/crates/hir_def/src/db.rs b/crates/hir_def/src/db.rs
index 7fe6f6346..6c01f1ed0 100644
--- a/crates/hir_def/src/db.rs
+++ b/crates/hir_def/src/db.rs
@@ -58,6 +58,21 @@ pub trait DefDatabase: InternDatabase + AstDatabase + Upcast<dyn AstDatabase> {
     #[salsa::invoke(DefMap::crate_def_map_query)]
     fn crate_def_map_query(&self, krate: CrateId) -> Arc<DefMap>;
 
+    /// Computes the block-level `DefMap`, returning `None` when `block` doesn't contain any inner
+    /// items directly.
+    ///
+    /// For example:
+    ///
+    /// ```
+    /// fn f() { // (0)
+    ///     { // (1)
+    ///         fn inner() {}
+    ///     }
+    /// }
+    /// ```
+    ///
+    /// The `block_def_map` for block 0 would return `None`, while `block_def_map` of block 1 would
+    /// return a `DefMap` containing `inner`.
     #[salsa::invoke(DefMap::block_def_map_query)]
     fn block_def_map(&self, block: BlockId) -> Option<Arc<DefMap>>;
 
diff --git a/crates/hir_def/src/nameres.rs b/crates/hir_def/src/nameres.rs
index ece5958f4..ef54f7d08 100644
--- a/crates/hir_def/src/nameres.rs
+++ b/crates/hir_def/src/nameres.rs
@@ -73,7 +73,15 @@ use crate::{
     AstId, BlockId, BlockLoc, LocalModuleId, ModuleDefId, ModuleId,
 };
 
-/// Contains all top-level defs from a macro-expanded crate
+/// Contains the results of (early) name resolution.
+///
+/// A `DefMap` stores the module tree and the definitions that are in scope in every module after
+/// item-level macros have been expanded.
+///
+/// Every crate has a primary `DefMap` whose root is the crate's main file (`main.rs`/`lib.rs`),
+/// computed by the `crate_def_map` query. Additionally, every block expression introduces the
+/// opportunity to write arbitrary item and module hierarchies, and thus gets its own `DefMap` that
+/// is computed by the `block_def_map` query.
 #[derive(Debug, PartialEq, Eq)]
 pub struct DefMap {
     _c: Count<Self>,
@@ -91,6 +99,7 @@ pub struct DefMap {
     diagnostics: Vec<DefDiagnostic>,
 }
 
+/// For `DefMap`s computed for a block expression, this stores its location in the parent map.
 #[derive(Debug, PartialEq, Eq)]
 struct BlockInfo {
     block: BlockId,