From 2c916bbc189da3dc5a1e34b3cdcfcb5e30d42af7 Mon Sep 17 00:00:00 2001 From: Aleksey Kladov Date: Mon, 21 Sep 2020 12:30:55 +0200 Subject: Document SemanticScope --- crates/hir/src/semantics.rs | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) (limited to 'crates/hir') diff --git a/crates/hir/src/semantics.rs b/crates/hir/src/semantics.rs index 0516a05b4..c23a52b7c 100644 --- a/crates/hir/src/semantics.rs +++ b/crates/hir/src/semantics.rs @@ -697,6 +697,25 @@ fn find_root(node: &SyntaxNode) -> SyntaxNode { node.ancestors().last().unwrap() } +/// `SemanticScope` encapsulates the notion of a scope (the set of visible +/// names) at a particular program point. +/// +/// It is a bit tricky, as scopes do not really exist inside the compiler. +/// Rather, the compiler directly computes for each reference the definition it +/// refers to. It might transiently compute the explicit scope map while doing +/// so, but, generally, this is not something left after the analysis. +/// +/// However, we do very much need explicit scopes for IDE purposes -- +/// completion, at its core, lists the contents of the current scope. Notion of +/// scope is also useful to answer question like "what would be the meaning of +/// this piece of code if we insert into this position?". +/// +/// So `SemanticsScope` is constructed from a specific program point (a syntax +/// node or just a raw offset) and provides access to the set of visible names +/// in on a somewhat best-effort basis. +/// +/// Note that if you are wondering "what this specific existing name means?", +/// you'd better use the `resolve_` family of methods. #[derive(Debug)] pub struct SemanticsScope<'a> { pub db: &'a dyn HirDatabase, -- cgit v1.2.3