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(+) 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 From 8e3082ff6e622c17a93bec34d2ddbd6f63609512 Mon Sep 17 00:00:00 2001 From: Aleksey Kladov Date: Mon, 21 Sep 2020 12:36:51 +0200 Subject: Document AstTransformation --- crates/assists/src/ast_transform.rs | 28 ++++++++++++++++++++++++++++ 1 file changed, 28 insertions(+) diff --git a/crates/assists/src/ast_transform.rs b/crates/assists/src/ast_transform.rs index bbcd2d488..835da3bb2 100644 --- a/crates/assists/src/ast_transform.rs +++ b/crates/assists/src/ast_transform.rs @@ -18,6 +18,34 @@ pub fn apply<'a, N: AstNode>(transformer: &dyn AstTransform<'a>, node: N) -> N { .rewrite_ast(&node) } +/// `AstTransform` helps with applying bulk transformations to syntax nodes. +/// +/// This is mostly useful for IDE code generation. If you paste some existing +/// code into a new context (for example, to add method overrides to an `impl` +/// block), you generally want to appropriately qualify the names, and sometimes +/// you might want to substitute generic parameters as well: +/// +/// ``` +/// mod x { +/// pub struct A; +/// pub trait T { fn foo(&self, _: U) -> A; } +/// } +/// +/// mod y { +/// use x::T; +/// +/// impl T<()> for () { +/// // If we invoke **Add Missing Members** here, we want to copy-paste `foo`. +/// // But we want a slightly-modified version of it: +/// fn foo(&self, _: ()) -> x::A {} +/// } +/// } +/// ``` +/// +/// So, a single `AstTransform` describes such function from `SyntaxNode` to +/// `SyntaxNode`. Note that the API here is a bit too high-order and high-brow. +/// We'd want to somehow express this concept simpler, but so far nobody got to +/// simplifying this! pub trait AstTransform<'a> { fn get_substitution(&self, node: &syntax::SyntaxNode) -> Option; -- cgit v1.2.3 From fcc3c49013c681d7f7cc98a59fe140e076837813 Mon Sep 17 00:00:00 2001 From: Aleksey Kladov Date: Mon, 21 Sep 2020 15:35:42 +0300 Subject: Apply suggestions from code review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Laurențiu Nicola --- crates/hir/src/semantics.rs | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/crates/hir/src/semantics.rs b/crates/hir/src/semantics.rs index c23a52b7c..c61a430e1 100644 --- a/crates/hir/src/semantics.rs +++ b/crates/hir/src/semantics.rs @@ -706,15 +706,15 @@ fn find_root(node: &SyntaxNode) -> SyntaxNode { /// 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?". +/// completion, at its core, lists the contents of the current scope. The notion +/// of scope is also useful to answer questions like "what would be the meaning +/// of this piece of code if we inserted it 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. +/// on a somewhat best-effort basis. /// -/// Note that if you are wondering "what this specific existing name means?", +/// Note that if you are wondering "what does this specific existing name mean?", /// you'd better use the `resolve_` family of methods. #[derive(Debug)] pub struct SemanticsScope<'a> { -- cgit v1.2.3