Update `DefMap` and `block_def_map` docs

1 files changed, 15 insertions, 0 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>>;