diff options
author | Jonas Schievink <[email protected]> | 2021-05-23 22:09:38 +0100 |
---|---|---|
committer | Jonas Schievink <[email protected]> | 2021-05-23 22:09:38 +0100 |
commit | 693325fc39363c04d4efcf4a2e575b6ab1bac383 (patch) | |
tree | 0f6bc9e01b63bc1a66dc1a4f0b3ff232ac7bba7f | |
parent | 951c0e95f44bf7947c2a46ef9e8ff2616823faba (diff) |
internal: document ItemTree design
-rw-r--r-- | crates/hir_def/src/item_tree.rs | 34 |
1 files changed, 32 insertions, 2 deletions
diff --git a/crates/hir_def/src/item_tree.rs b/crates/hir_def/src/item_tree.rs index 528270d49..4a5f44027 100644 --- a/crates/hir_def/src/item_tree.rs +++ b/crates/hir_def/src/item_tree.rs | |||
@@ -1,4 +1,34 @@ | |||
1 | //! A simplified AST that only contains items. | 1 | //! A simplified AST that only contains items. |
2 | //! | ||
3 | //! This is the primary IR used throughout `hir_def`. It is the input to the name resolution | ||
4 | //! algorithm, as well as to the queries defined in `adt.rs`, `data.rs`, and most things in | ||
5 | //! `attr.rs`. | ||
6 | //! | ||
7 | //! `ItemTree`s are built per `HirFileId`, from the syntax tree of the parsed file. This means that | ||
8 | //! they are crate-independent: they don't know which `#[cfg]`s are active or which module they | ||
9 | //! belong to, since those concepts don't exist at this level (a single `ItemTree` might be part of | ||
10 | //! multiple crates, or might be included into the same crate twice via `#[path]`). | ||
11 | //! | ||
12 | //! One important purpose of this layer is to provide an "invalidation barrier" for incremental | ||
13 | //! computations: when typing inside an item body, the `ItemTree` of the modified file is typically | ||
14 | //! unaffected, so we don't have to recompute name resolution results or item data (see `data.rs`). | ||
15 | //! | ||
16 | //! The `ItemTree` for the currently open file can be displayed by using the VS Code command | ||
17 | //! "Rust Analyzer: Debug ItemTree". | ||
18 | //! | ||
19 | //! Compared to rustc's architecture, `ItemTree` has properties from both rustc's AST and HIR: many | ||
20 | //! syntax-level Rust features are already desugared to simpler forms in the `ItemTree`, but name | ||
21 | //! resolution has not yet been performed. `ItemTree`s are per-file, while rustc's AST and HIR are | ||
22 | //! per-crate, because we are interested in incrementally computing it. | ||
23 | //! | ||
24 | //! The representation of items in the `ItemTree` should generally mirror the surface syntax: it is | ||
25 | //! usually a bad idea to desugar a syntax-level construct to something that is structurally | ||
26 | //! different here. Name resolution needs to be able to process attributes and expand macros | ||
27 | //! (including attribute macros), and having a 1-to-1 mapping between syntax and the `ItemTree` | ||
28 | //! avoids introducing subtle bugs. | ||
29 | //! | ||
30 | //! In general, any item in the `ItemTree` stores its `AstId`, which allows mapping it back to its | ||
31 | //! surface syntax. | ||
2 | 32 | ||
3 | mod lower; | 33 | mod lower; |
4 | mod pretty; | 34 | mod pretty; |
@@ -500,8 +530,8 @@ pub struct Import { | |||
500 | pub alias: Option<ImportAlias>, | 530 | pub alias: Option<ImportAlias>, |
501 | pub visibility: RawVisibilityId, | 531 | pub visibility: RawVisibilityId, |
502 | pub is_glob: bool, | 532 | pub is_glob: bool, |
503 | /// AST ID of the `use` or `extern crate` item this import was derived from. Note that many | 533 | /// AST ID of the `use` item this import was derived from. Note that many `Import`s can map to |
504 | /// `Import`s can map to the same `use` item. | 534 | /// the same `use` item. |
505 | pub ast_id: FileAstId<ast::Use>, | 535 | pub ast_id: FileAstId<ast::Use>, |
506 | /// Index of this `Import` when the containing `Use` is visited via `ModPath::expand_use_item`. | 536 | /// Index of this `Import` when the containing `Use` is visited via `ModPath::expand_use_item`. |
507 | /// | 537 | /// |