fix the docs

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
+`hir`.
 
-An LSP implementation which uses `ra_analysis` for managing state and
+### `crates/ra_ide_api_light`
-`ra_editor` for actually doing useful stuff.
 
-See [#79](https://github.com/rust-analyzer/rust-analyzer/pull/79/) as an
+All IDE features which can be implemented if you only have access to a single
-example of PR which adds a new feature to `ra_editor` and exposes it
+file. `ra_ide_api_light` could be used to enhance editing of Rust code without
-to `ra_lsp_server`.
+the need to fiddle with build-systems, file synchronization and such.
 
-### `crates/ra_editor`
+In a sense, `ra_ide_api_light` is just a bunch of pure functions which take a
-
-All IDE features which can be implemented if you only have access to a
-single file. `ra_editor` could be used to enhance editing of Rust code
-without the need to fiddle with build-systems, file
-synchronization and such.
-
-In a sense, `ra_editor` 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.

crates/ra_db/src/lib.rs

@@ -1,4 +1,4 @@
-//! ra_db defines basic database traits. Concrete DB is defined by ra_analysis.
+//! ra_db defines basic database traits. Concrete DB is defined by ra_ide_api.
 mod cancelation;
 mod syntax_ptr;
 mod input;

crates/ra_ide_api/src/lib.rs

@@ -1,8 +1,14 @@
-//! ra_analyzer crate provides "ide-centric" APIs for the rust-analyzer. What
+//! ra_ide_api crate provides "ide-centric" APIs for the rust-analyzer. That is,
-//! powers this API are the `RootDatabase` struct, which defines a `salsa`
+//! it generally operates with files and text ranges, and returns results as
+//! Strings, suitable for displaying to the human.
+//!
+//! What powers this API are the `RootDatabase` struct, which defines a `salsa`
 //! database, and the `ra_hir` crate, where majority of the analysis happens.
 //! However, IDE specific bits of the analysis (most notably completion) happen
 //! in this crate.
+//!
+//! The sibling `ra_ide_api_light` handles thouse bits of IDE functionality
+//! which are restricted to a single file and need only syntax.
 macro_rules! ctry {
     ($expr:expr) => {
         match $expr {