2 files changed, 9 insertions, 3 deletions

diff --git a/crates/ra_db/src/lib.rs b/crates/ra_db/src/lib.rs
index f56f70983..e680d9fc3 100644
--- a/crates/ra_db/src/lib.rs
+++ b/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;
diff --git a/crates/ra_ide_api/src/lib.rs b/crates/ra_ide_api/src/lib.rs
index 183e36706..7e9ca2034 100644
--- a/crates/ra_ide_api/src/lib.rs
+++ b/crates/ra_ide_api/src/lib.rs
@@ -1,8 +1,14 @@
-//! ra_analyzer crate provides "ide-centric" APIs for the rust-analyzer. What
-//! powers this API are the `RootDatabase` struct, which defines a `salsa`
+//! ra_ide_api crate provides "ide-centric" APIs for the rust-analyzer. That is,
+//! 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 {