1 files changed, 31 insertions, 26 deletions
diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md
index 277b29c12..9c404f4c3 100644
--- a/ARCHITECTURE.md
+++ b/ARCHITECTURE.md
@@ -15,7 +15,7 @@ More specifically, input data consists of a set of test files (`(PathBuf,
 String)` pairs) and an information about project structure, the so called
 `CrateGraph`. Crate graph specifies which files are crate roots, which cfg flags
 are specified for each crate (TODO: actually implement this) and what are
-dependencies between the crate. The analyzer keeps all these input data in
+dependencies between the crates. The analyzer keeps all these input data in
 memory and never does any IO. Because the input data is source code, which
 typically measures in tens of megabytes at most, keeping all input data in
 memory is OK.
@@ -74,9 +74,9 @@ notes.
 - `algo`: generic tree algorithms, including `walk` for O(1) stack
  space tree traversal (this is cool) and `visit` for type-driven
  visiting the nodes (this is double plus cool, if you understand how
-  `Visitor` works, you understand rust-analyzer).
+  `Visitor` works, you understand the design of syntax trees).
-Test for ra_syntax are mostly data-driven: `tests/data/parser` contains a bunch of `.rs`
+Tests for ra_syntax are mostly data-driven: `tests/data/parser` contains a bunch of `.rs`
 (test vectors) and `.txt` files with corresponding syntax trees. During testing, we check
 `.rs` against `.txt`. If the `.txt` file is missing, it is created (this is how you update
 tests). Additionally, running `cargo gen-tests` will walk the grammar module and collect
@@ -107,41 +107,46 @@ guessing a HIR for a particular source position.
 Underneath, HIR works on top of salsa, using a `HirDatabase` trait.
-### `crates/ra_analysis`
+### `crates/ra_ide_api`
-A stateful library for analyzing many Rust files as they change.
+A stateful library for analyzing many Rust files as they change. `AnalysisHost`
-`AnalysisHost` is a mutable entity (clojure's atom) which holds the
+is a mutable entity (clojure's atom) which holds the current state, incorporates
-current state, incorporates changes and handles out `Analysis` --- an
+changes and handles out `Analysis` --- an immutable and consistent snapshot of
-immutable and consistent snapshot of world state at a point in time, which
+world state at a point in time, which actually powers analysis.
-actually powers analysis.
-One interesting aspect of analysis is its support for cancellation. When a change
+One interesting aspect of analysis is its support for cancellation. When a
-is applied to `AnalysisHost`, first all currently active snapshots are
+change is applied to `AnalysisHost`, first all currently active snapshots are
 cancelled. Only after all snapshots are dropped the change actually affects the
 database.
-### `crates/ra_lsp_server`
+APIs in this crate are IDE centric: they take text offsets as input and produce
+offsets and strings as output. This works on top of rich code model powered by
-An LSP implementation which uses `ra_analysis` for managing state and
+`hir`.
-`ra_editor` for actually doing useful stuff.
-See [#79](https://github.com/rust-analyzer/rust-analyzer/pull/79/) as an
-example of PR which adds a new feature to `ra_editor` and exposes it
-to `ra_lsp_server`.
-### `crates/ra_editor`
+### `crates/ra_ide_api_light`
-All IDE features which can be implemented if you only have access to a
+All IDE features which can be implemented if you only have access to a single
-single file. `ra_editor` could be used to enhance editing of Rust code
+file. `ra_ide_api_light` could be used to enhance editing of Rust code without
-without the need to fiddle with build-systems, file
+the need to fiddle with build-systems, file synchronization and such.
-synchronization and such.
-In a sense, `ra_editor` is just a bunch of pure functions which take a
+In a sense, `ra_ide_api_light` is just a bunch of pure functions which take a
 syntax tree as input.
-The tests for `ra_editor` are `#[cfg(test)] mod tests` unit-tests spread
+The tests for `ra_ide_api_light` are `#[cfg(test)] mod tests` unit-tests spread
 throughout its modules.
+### `crates/ra_lsp_server`
+An LSP implementation which wraps `ra_ide_api` into a langauge server protocol.
+### `crates/ra_vfs`
+Although `hir` and `ra_ide_api` don't do any io, we need to be able to read
+files from disk at the end of the day. This is what `ra_vfs` does. It also
+manages overlays: "dirty" files in the editor, whose "true" contents is
+different from data on disk.
 ### `crates/gen_lsp_server`
 A language server scaffold, exposing a synchronous crossbeam-channel based API.

diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index 277b29c12..9c404f4c3 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md
@@ -15,7 +15,7 @@ More specifically, input data consists of a set of test files (`(PathBuf,
15	String)` pairs) and an information about project structure, the so called	15	String)` pairs) and an information about project structure, the so called
16	`CrateGraph`. Crate graph specifies which files are crate roots, which cfg flags	16	`CrateGraph`. Crate graph specifies which files are crate roots, which cfg flags
17	are specified for each crate (TODO: actually implement this) and what are	17	are specified for each crate (TODO: actually implement this) and what are
18	dependencies between the crate. The analyzer keeps all these input data in	18	dependencies between the crates. The analyzer keeps all these input data in
19	memory and never does any IO. Because the input data is source code, which	19	memory and never does any IO. Because the input data is source code, which
20	typically measures in tens of megabytes at most, keeping all input data in	20	typically measures in tens of megabytes at most, keeping all input data in
21	memory is OK.	21	memory is OK.
@@ -74,9 +74,9 @@ notes.
74	- `algo`: generic tree algorithms, including `walk` for O(1) stack	74	- `algo`: generic tree algorithms, including `walk` for O(1) stack
75	space tree traversal (this is cool) and `visit` for type-driven	75	space tree traversal (this is cool) and `visit` for type-driven
76	visiting the nodes (this is double plus cool, if you understand how	76	visiting the nodes (this is double plus cool, if you understand how
77	`Visitor` works, you understand rust-analyzer).	77	`Visitor` works, you understand the design of syntax trees).
78		78
79	Test for ra_syntax are mostly data-driven: `tests/data/parser` contains a bunch of `.rs`	79	Tests for ra_syntax are mostly data-driven: `tests/data/parser` contains a bunch of `.rs`
80	(test vectors) and `.txt` files with corresponding syntax trees. During testing, we check	80	(test vectors) and `.txt` files with corresponding syntax trees. During testing, we check
81	`.rs` against `.txt`. If the `.txt` file is missing, it is created (this is how you update	81	`.rs` against `.txt`. If the `.txt` file is missing, it is created (this is how you update
82	tests). Additionally, running `cargo gen-tests` will walk the grammar module and collect	82	tests). Additionally, running `cargo gen-tests` will walk the grammar module and collect
@@ -107,41 +107,46 @@ guessing a HIR for a particular source position.
107		107
108	Underneath, HIR works on top of salsa, using a `HirDatabase` trait.	108	Underneath, HIR works on top of salsa, using a `HirDatabase` trait.
109		109
110	### `crates/ra_analysis`	110	### `crates/ra_ide_api`
111		111
112	A stateful library for analyzing many Rust files as they change.	112	A stateful library for analyzing many Rust files as they change. `AnalysisHost`
113	`AnalysisHost` is a mutable entity (clojure's atom) which holds the	113	is a mutable entity (clojure's atom) which holds the current state, incorporates
114	current state, incorporates changes and handles out `Analysis` --- an	114	changes and handles out `Analysis` --- an immutable and consistent snapshot of
115	immutable and consistent snapshot of world state at a point in time, which	115	world state at a point in time, which actually powers analysis.
116	actually powers analysis.
117		116
118	One interesting aspect of analysis is its support for cancellation. When a change	117	One interesting aspect of analysis is its support for cancellation. When a
119	is applied to `AnalysisHost`, first all currently active snapshots are	118	change is applied to `AnalysisHost`, first all currently active snapshots are
120	cancelled. Only after all snapshots are dropped the change actually affects the	119	cancelled. Only after all snapshots are dropped the change actually affects the
121	database.	120	database.
122		121
123	### `crates/ra_lsp_server`	122	APIs in this crate are IDE centric: they take text offsets as input and produce
124		123	offsets and strings as output. This works on top of rich code model powered by
125	An LSP implementation which uses `ra_analysis` for managing state and	124	`hir`.
126	`ra_editor` for actually doing useful stuff.
127
128	See [#79](https://github.com/rust-analyzer/rust-analyzer/pull/79/) as an
129	example of PR which adds a new feature to `ra_editor` and exposes it
130	to `ra_lsp_server`.
131		125
132	### `crates/ra_editor`	126	### `crates/ra_ide_api_light`
133		127
134	All IDE features which can be implemented if you only have access to a	128	All IDE features which can be implemented if you only have access to a single
135	single file. `ra_editor` could be used to enhance editing of Rust code	129	file. `ra_ide_api_light` could be used to enhance editing of Rust code without
136	without the need to fiddle with build-systems, file	130	the need to fiddle with build-systems, file synchronization and such.
137	synchronization and such.
138		131
139	In a sense, `ra_editor` is just a bunch of pure functions which take a	132	In a sense, `ra_ide_api_light` is just a bunch of pure functions which take a
140	syntax tree as input.	133	syntax tree as input.
141		134
142	The tests for `ra_editor` are `#[cfg(test)] mod tests` unit-tests spread	135	The tests for `ra_ide_api_light` are `#[cfg(test)] mod tests` unit-tests spread
143	throughout its modules.	136	throughout its modules.
144		137
		138
		139	### `crates/ra_lsp_server`
		140
		141	An LSP implementation which wraps `ra_ide_api` into a langauge server protocol.
		142
		143	### `crates/ra_vfs`
		144
		145	Although `hir` and `ra_ide_api` don't do any io, we need to be able to read
		146	files from disk at the end of the day. This is what `ra_vfs` does. It also
		147	manages overlays: "dirty" files in the editor, whose "true" contents is
		148	different from data on disk.
		149
145	### `crates/gen_lsp_server`	150	### `crates/gen_lsp_server`
146		151
147	A language server scaffold, exposing a synchronous crossbeam-channel based API.	152	A language server scaffold, exposing a synchronous crossbeam-channel based API.