aboutsummaryrefslogtreecommitdiff
path: root/docs/dev
diff options
context:
space:
mode:
Diffstat (limited to 'docs/dev')
-rw-r--r--docs/dev/README.md6
-rw-r--r--docs/dev/architecture.md6
-rw-r--r--docs/dev/guide.md38
3 files changed, 25 insertions, 25 deletions
diff --git a/docs/dev/README.md b/docs/dev/README.md
index 4aab6e2b8..04bebbfca 100644
--- a/docs/dev/README.md
+++ b/docs/dev/README.md
@@ -148,14 +148,14 @@ Internal representations are lowered to LSP in the `rust-analyzer` crate (the on
148 148
149## IDE/Compiler split 149## IDE/Compiler split
150 150
151There's a semi-hard split between "compiler" and "IDE", at the `ra_hir` crate. 151There's a semi-hard split between "compiler" and "IDE", at the `hir` crate.
152Compiler derives new facts about source code. 152Compiler derives new facts about source code.
153It explicitly acknowledges that not all info is available (i.e. you can't look at types during name resolution). 153It explicitly acknowledges that not all info is available (i.e. you can't look at types during name resolution).
154 154
155IDE assumes that all information is available at all times. 155IDE assumes that all information is available at all times.
156 156
157IDE should use only types from `ra_hir`, and should not depend on the underling compiler types. 157IDE should use only types from `hir`, and should not depend on the underling compiler types.
158`ra_hir` is a facade. 158`hir` is a facade.
159 159
160## IDE API 160## IDE API
161 161
diff --git a/docs/dev/architecture.md b/docs/dev/architecture.md
index 746d41f83..0ffe61026 100644
--- a/docs/dev/architecture.md
+++ b/docs/dev/architecture.md
@@ -102,7 +102,7 @@ defines most of the "input" queries: facts supplied by the client of the
102analyzer. Reading the docs of the `base_db::input` module should be useful: 102analyzer. Reading the docs of the `base_db::input` module should be useful:
103everything else is strictly derived from those inputs. 103everything else is strictly derived from those inputs.
104 104
105### `crates/ra_hir*` crates 105### `crates/hir*` crates
106 106
107HIR provides high-level "object oriented" access to Rust code. 107HIR provides high-level "object oriented" access to Rust code.
108 108
@@ -113,10 +113,10 @@ is responsible for guessing a HIR for a particular source position.
113 113
114Underneath, HIR works on top of salsa, using a `HirDatabase` trait. 114Underneath, HIR works on top of salsa, using a `HirDatabase` trait.
115 115
116`ra_hir_xxx` crates have a strong ECS flavor, in that they work with raw ids and 116`hir_xxx` crates have a strong ECS flavor, in that they work with raw ids and
117directly query the database. 117directly query the database.
118 118
119The top-level `ra_hir` façade crate wraps ids into a more OO-flavored API. 119The top-level `hir` façade crate wraps ids into a more OO-flavored API.
120 120
121### `crates/ra_ide` 121### `crates/ra_ide`
122 122
diff --git a/docs/dev/guide.md b/docs/dev/guide.md
index d14143226..29d84bf3f 100644
--- a/docs/dev/guide.md
+++ b/docs/dev/guide.md
@@ -275,7 +275,7 @@ several times, with different sets of `cfg`s enabled. The IDE-specific task of
275mapping source code position into a semantic model is inherently imprecise for 275mapping source code position into a semantic model is inherently imprecise for
276this reason, and is handled by the [`source_binder`]. 276this reason, and is handled by the [`source_binder`].
277 277
278[`source_binder`]: https://github.com/rust-analyzer/rust-analyzer/blob/guide-2019-01/crates/ra_hir/src/source_binder.rs 278[`source_binder`]: https://github.com/rust-analyzer/rust-analyzer/blob/guide-2019-01/crates/hir/src/source_binder.rs
279 279
280The semantic interface is declared in the [`code_model_api`] module. Each entity is 280The semantic interface is declared in the [`code_model_api`] module. Each entity is
281identified by an integer ID and has a bunch of methods which take a salsa database 281identified by an integer ID and has a bunch of methods which take a salsa database
@@ -283,8 +283,8 @@ as an argument and returns other entities (which are also IDs). Internally, thes
283methods invoke various queries on the database to build the model on demand. 283methods invoke various queries on the database to build the model on demand.
284Here's [the list of queries]. 284Here's [the list of queries].
285 285
286[`code_model_api`]: https://github.com/rust-analyzer/rust-analyzer/blob/guide-2019-01/crates/ra_hir/src/code_model_api.rs 286[`code_model_api`]: https://github.com/rust-analyzer/rust-analyzer/blob/guide-2019-01/crates/hir/src/code_model_api.rs
287[the list of queries]: https://github.com/rust-analyzer/rust-analyzer/blob/7e84440e25e19529e4ff8a66e521d1b06349c6ec/crates/ra_hir/src/db.rs#L20-L106 287[the list of queries]: https://github.com/rust-analyzer/rust-analyzer/blob/7e84440e25e19529e4ff8a66e521d1b06349c6ec/crates/hir/src/db.rs#L20-L106
288 288
289The first step of building the model is parsing the source code. 289The first step of building the model is parsing the source code.
290 290
@@ -341,7 +341,7 @@ The algorithm for building a tree of modules is to start with a crate root
341declarations and recursively process child modules. This is handled by the 341declarations and recursively process child modules. This is handled by the
342[`module_tree_query`], with two slight variations. 342[`module_tree_query`], with two slight variations.
343 343
344[`module_tree_query`]: https://github.com/rust-analyzer/rust-analyzer/blob/guide-2019-01/crates/ra_hir/src/module_tree.rs#L116-L123 344[`module_tree_query`]: https://github.com/rust-analyzer/rust-analyzer/blob/guide-2019-01/crates/hir/src/module_tree.rs#L116-L123
345 345
346First, rust-analyzer builds a module tree for all crates in a source root 346First, rust-analyzer builds a module tree for all crates in a source root
347simultaneously. The main reason for this is historical (`module_tree` predates 347simultaneously. The main reason for this is historical (`module_tree` predates
@@ -364,7 +364,7 @@ the same, we don't have to re-execute [`module_tree_query`]. In fact, we only
364need to re-execute it when we add/remove new files or when we change mod 364need to re-execute it when we add/remove new files or when we change mod
365declarations. 365declarations.
366 366
367[`submodules_query`]: https://github.com/rust-analyzer/rust-analyzer/blob/guide-2019-01/crates/ra_hir/src/module_tree.rs#L41 367[`submodules_query`]: https://github.com/rust-analyzer/rust-analyzer/blob/guide-2019-01/crates/hir/src/module_tree.rs#L41
368 368
369We store the resulting modules in a `Vec`-based indexed arena. The indices in 369We store the resulting modules in a `Vec`-based indexed arena. The indices in
370the arena becomes module IDs. And this brings us to the next topic: 370the arena becomes module IDs. And this brings us to the next topic:
@@ -393,7 +393,7 @@ database we use includes a couple of [interners]. How to "garbage collect"
393unused locations is an open question. 393unused locations is an open question.
394 394
395[`LocationInterner`]: https://github.com/rust-analyzer/rust-analyzer/blob/guide-2019-01/crates/base_db/src/loc2id.rs#L65-L71 395[`LocationInterner`]: https://github.com/rust-analyzer/rust-analyzer/blob/guide-2019-01/crates/base_db/src/loc2id.rs#L65-L71
396[interners]: https://github.com/rust-analyzer/rust-analyzer/blob/guide-2019-01/crates/ra_hir/src/db.rs#L22-L23 396[interners]: https://github.com/rust-analyzer/rust-analyzer/blob/guide-2019-01/crates/hir/src/db.rs#L22-L23
397 397
398For example, we use `LocationInterner` to assign IDs to definitions of functions, 398For example, we use `LocationInterner` to assign IDs to definitions of functions,
399structs, enums, etc. The location, [`DefLoc`] contains two bits of information: 399structs, enums, etc. The location, [`DefLoc`] contains two bits of information:
@@ -407,7 +407,7 @@ using offsets, text ranges or syntax trees as keys and values for queries. What
407we do instead is we store "index" of the item among all of the items of a file 407we do instead is we store "index" of the item among all of the items of a file
408(so, a positional based ID, but localized to a single file). 408(so, a positional based ID, but localized to a single file).
409 409
410[`DefLoc`]: https://github.com/rust-analyzer/rust-analyzer/blob/guide-2019-01/crates/ra_hir/src/ids.rs#L127-L139 410[`DefLoc`]: https://github.com/rust-analyzer/rust-analyzer/blob/guide-2019-01/crates/hir/src/ids.rs#L127-L139
411 411
412One thing we've glossed over for the time being is support for macros. We have 412One thing we've glossed over for the time being is support for macros. We have
413only proof of concept handling of macros at the moment, but they are extremely 413only proof of concept handling of macros at the moment, but they are extremely
@@ -440,7 +440,7 @@ terms of `HirFileId`! This does not recur infinitely though: any chain of
440`HirFileId`s bottoms out in `HirFileId::FileId`, that is, some source file 440`HirFileId`s bottoms out in `HirFileId::FileId`, that is, some source file
441actually written by the user. 441actually written by the user.
442 442
443[`HirFileId`]: https://github.com/rust-analyzer/rust-analyzer/blob/guide-2019-01/crates/ra_hir/src/ids.rs#L18-L125 443[`HirFileId`]: https://github.com/rust-analyzer/rust-analyzer/blob/guide-2019-01/crates/hir/src/ids.rs#L18-L125
444 444
445Now that we understand how to identify a definition, in a source or in a 445Now that we understand how to identify a definition, in a source or in a
446macro-generated file, we can discuss name resolution a bit. 446macro-generated file, we can discuss name resolution a bit.
@@ -454,14 +454,14 @@ each module into a position-independent representation which does not change if
454we modify bodies of the items. After that we [loop] resolving all imports until 454we modify bodies of the items. After that we [loop] resolving all imports until
455we've reached a fixed point. 455we've reached a fixed point.
456 456
457[lower]: https://github.com/rust-analyzer/rust-analyzer/blob/guide-2019-01/crates/ra_hir/src/nameres/lower.rs#L113-L117 457[lower]: https://github.com/rust-analyzer/rust-analyzer/blob/guide-2019-01/crates/hir/src/nameres/lower.rs#L113-L117
458[loop]: https://github.com/rust-analyzer/rust-analyzer/blob/guide-2019-01/crates/ra_hir/src/nameres.rs#L186-L196 458[loop]: https://github.com/rust-analyzer/rust-analyzer/blob/guide-2019-01/crates/hir/src/nameres.rs#L186-L196
459 459
460And, given all our preparation with IDs and a position-independent representation, 460And, given all our preparation with IDs and a position-independent representation,
461it is satisfying to [test] that typing inside function body does not invalidate 461it is satisfying to [test] that typing inside function body does not invalidate
462name resolution results. 462name resolution results.
463 463
464[test]: https://github.com/rust-analyzer/rust-analyzer/blob/guide-2019-01/crates/ra_hir/src/nameres/tests.rs#L376 464[test]: https://github.com/rust-analyzer/rust-analyzer/blob/guide-2019-01/crates/hir/src/nameres/tests.rs#L376
465 465
466An interesting fact about name resolution is that it "erases" all of the 466An interesting fact about name resolution is that it "erases" all of the
467intermediate paths from the imports: in the end, we know which items are defined 467intermediate paths from the imports: in the end, we know which items are defined
@@ -496,10 +496,10 @@ there's an intermediate [projection query] which returns only the first
496position-independent part of the lowering. The result of this query is stable. 496position-independent part of the lowering. The result of this query is stable.
497Naturally, name resolution [uses] this stable projection query. 497Naturally, name resolution [uses] this stable projection query.
498 498
499[imports]: https://github.com/rust-analyzer/rust-analyzer/blob/guide-2019-01/crates/ra_hir/src/nameres/lower.rs#L52-L59 499[imports]: https://github.com/rust-analyzer/rust-analyzer/blob/guide-2019-01/crates/hir/src/nameres/lower.rs#L52-L59
500[`SourceMap`]: https://github.com/rust-analyzer/rust-analyzer/blob/guide-2019-01/crates/ra_hir/src/nameres/lower.rs#L52-L59 500[`SourceMap`]: https://github.com/rust-analyzer/rust-analyzer/blob/guide-2019-01/crates/hir/src/nameres/lower.rs#L52-L59
501[projection query]: https://github.com/rust-analyzer/rust-analyzer/blob/guide-2019-01/crates/ra_hir/src/nameres/lower.rs#L97-L103 501[projection query]: https://github.com/rust-analyzer/rust-analyzer/blob/guide-2019-01/crates/hir/src/nameres/lower.rs#L97-L103
502[uses]: https://github.com/rust-analyzer/rust-analyzer/blob/guide-2019-01/crates/ra_hir/src/query_definitions.rs#L49 502[uses]: https://github.com/rust-analyzer/rust-analyzer/blob/guide-2019-01/crates/hir/src/query_definitions.rs#L49
503 503
504## Type inference 504## Type inference
505 505
@@ -521,10 +521,10 @@ construct a mapping from `ExprId`s to types.
521 521
522[@flodiebold]: https://github.com/flodiebold 522[@flodiebold]: https://github.com/flodiebold
523[#327]: https://github.com/rust-analyzer/rust-analyzer/pull/327 523[#327]: https://github.com/rust-analyzer/rust-analyzer/pull/327
524[lower the AST]: https://github.com/rust-analyzer/rust-analyzer/blob/guide-2019-01/crates/ra_hir/src/expr.rs 524[lower the AST]: https://github.com/rust-analyzer/rust-analyzer/blob/guide-2019-01/crates/hir/src/expr.rs
525[positional ID]: https://github.com/rust-analyzer/rust-analyzer/blob/guide-2019-01/crates/ra_hir/src/expr.rs#L13-L15 525[positional ID]: https://github.com/rust-analyzer/rust-analyzer/blob/guide-2019-01/crates/hir/src/expr.rs#L13-L15
526[a source map]: https://github.com/rust-analyzer/rust-analyzer/blob/guide-2019-01/crates/ra_hir/src/expr.rs#L41-L44 526[a source map]: https://github.com/rust-analyzer/rust-analyzer/blob/guide-2019-01/crates/hir/src/expr.rs#L41-L44
527[type inference]: https://github.com/rust-analyzer/rust-analyzer/blob/guide-2019-01/crates/ra_hir/src/ty.rs#L1208-L1223 527[type inference]: https://github.com/rust-analyzer/rust-analyzer/blob/guide-2019-01/crates/hir/src/ty.rs#L1208-L1223
528 528
529## Tying it all together: completion 529## Tying it all together: completion
530 530