From 24b27abf9f3a57268d0fb7c9a1aa2ede2980195f Mon Sep 17 00:00:00 2001 From: veetaha Date: Tue, 12 May 2020 23:31:37 +0300 Subject: [PATCH] Add a doc comment on the difference between Name and NameRef ast nodes --- crates/ra_syntax/src/ast/generated/nodes.rs | 17 ++++++++++++++++- xtask/src/ast_src.rs | 17 ++++++++++++++++- 2 files changed, 32 insertions(+), 2 deletions(-) diff --git a/crates/ra_syntax/src/ast/generated/nodes.rs b/crates/ra_syntax/src/ast/generated/nodes.rs index 7ee4590ba93..7b236cd5291 100644 --- a/crates/ra_syntax/src/ast/generated/nodes.rs +++ b/crates/ra_syntax/src/ast/generated/nodes.rs @@ -1790,7 +1790,20 @@ pub fn self_token(&self) -> Option { support::token(&self.syntax, T pub fn crate_token(&self) -> Option { support::token(&self.syntax, T![crate]) } } /// Single identifier. -/// // TODO: clarify the difference between Name and NameRef +/// Note(@matklad): `Name` is for things that install a new name into the scope, +/// `NameRef` is a usage of a name. Most of the time, this definition/reference +/// distinction can be determined purely syntactically, ie in +/// ``` +/// fn foo() { foo() } +/// ``` +/// the first foo is `Name`, the second one is `NameRef`. +/// The notable exception are patterns, where in +/// `` +/// let x = 92 +/// ``` +/// `x` can be semantically either a name or a name ref, depeding on +/// wether there's an `x` constant in scope. +/// We use `Name` for patterns, and disambiguate semantically (see `NameClass` in ide_db). /// /// ``` /// let ❰ foo ❱ = bar; @@ -1807,6 +1820,8 @@ impl Name { pub fn ident_token(&self) -> Option { support::token(&self.syntax, T![ident]) } } /// Reference to a name. +/// See the explanation on the difference between `Name` and `NameRef` +/// in `Name` ast node docs. /// /// ``` /// let foo = ❰ bar ❱(❰ Baz(❰ bruh ❱) ❱; diff --git a/xtask/src/ast_src.rs b/xtask/src/ast_src.rs index d1e34e29965..79e5a608d67 100644 --- a/xtask/src/ast_src.rs +++ b/xtask/src/ast_src.rs @@ -1522,7 +1522,20 @@ struct TuplePat { T!['('], args: [Pat], T![')'] } struct Visibility { T![pub], T![super], T![self], T![crate] } /// Single identifier. - /// // TODO: clarify the difference between Name and NameRef + /// Note(@matklad): `Name` is for things that install a new name into the scope, + /// `NameRef` is a usage of a name. Most of the time, this definition/reference + /// distinction can be determined purely syntactically, ie in + /// ``` + /// fn foo() { foo() } + /// ``` + /// the first foo is `Name`, the second one is `NameRef`. + /// The notable exception are patterns, where in + /// `` + /// let x = 92 + /// ``` + /// `x` can be semantically either a name or a name ref, depeding on + /// wether there's an `x` constant in scope. + /// We use `Name` for patterns, and disambiguate semantically (see `NameClass` in ide_db). /// /// ``` /// let ❰ foo ❱ = bar; @@ -1534,6 +1547,8 @@ struct Visibility { T![pub], T![super], T![self], T![crate] } struct Name { T![ident] } /// Reference to a name. + /// See the explanation on the difference between `Name` and `NameRef` + /// in `Name` ast node docs. /// /// ``` /// let foo = ❰ bar ❱(❰ Baz(❰ bruh ❱) ❱; -- 2.44.0