aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorJonas Schievink <[email protected]>2021-05-23 22:09:38 +0100
committerJonas Schievink <[email protected]>2021-05-23 22:09:38 +0100
commit693325fc39363c04d4efcf4a2e575b6ab1bac383 (patch)
tree0f6bc9e01b63bc1a66dc1a4f0b3ff232ac7bba7f
parent951c0e95f44bf7947c2a46ef9e8ff2616823faba (diff)
internal: document ItemTree design
-rw-r--r--crates/hir_def/src/item_tree.rs34
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
3mod lower; 33mod lower;
4mod pretty; 34mod 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 ///