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 @@
 //! A simplified AST that only contains items.
+//!
+//! This is the primary IR used throughout `hir_def`. It is the input to the name resolution
+//! algorithm, as well as to the queries defined in `adt.rs`, `data.rs`, and most things in
+//! `attr.rs`.
+//!
+//! `ItemTree`s are built per `HirFileId`, from the syntax tree of the parsed file. This means that
+//! they are crate-independent: they don't know which `#[cfg]`s are active or which module they
+//! belong to, since those concepts don't exist at this level (a single `ItemTree` might be part of
+//! multiple crates, or might be included into the same crate twice via `#[path]`).
+//!
+//! One important purpose of this layer is to provide an "invalidation barrier" for incremental
+//! computations: when typing inside an item body, the `ItemTree` of the modified file is typically
+//! unaffected, so we don't have to recompute name resolution results or item data (see `data.rs`).
+//!
+//! The `ItemTree` for the currently open file can be displayed by using the VS Code command
+//! "Rust Analyzer: Debug ItemTree".
+//!
+//! Compared to rustc's architecture, `ItemTree` has properties from both rustc's AST and HIR: many
+//! syntax-level Rust features are already desugared to simpler forms in the `ItemTree`, but name
+//! resolution has not yet been performed. `ItemTree`s are per-file, while rustc's AST and HIR are
+//! per-crate, because we are interested in incrementally computing it.
+//!
+//! The representation of items in the `ItemTree` should generally mirror the surface syntax: it is
+//! usually a bad idea to desugar a syntax-level construct to something that is structurally
+//! different here. Name resolution needs to be able to process attributes and expand macros
+//! (including attribute macros), and having a 1-to-1 mapping between syntax and the `ItemTree`
+//! avoids introducing subtle bugs.
+//!
+//! In general, any item in the `ItemTree` stores its `AstId`, which allows mapping it back to its
+//! surface syntax.
 mod lower;
 mod pretty;
@@ -500,8 +530,8 @@ pub struct Import {
    pub alias: Option<ImportAlias>,
    pub visibility: RawVisibilityId,
    pub is_glob: bool,
-    /// AST ID of the `use` or `extern crate` item this import was derived from. Note that many
+    /// AST ID of the `use` item this import was derived from. Note that many `Import`s can map to
-    /// `Import`s can map to the same `use` item.
+    /// the same `use` item.
    pub ast_id: FileAstId<ast::Use>,
    /// Index of this `Import` when the containing `Use` is visited via `ModPath::expand_use_item`.
    ///

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	///