3 files changed, 25 insertions, 6 deletions

diff --git a/crates/project_model/src/cargo_workspace.rs b/crates/project_model/src/cargo_workspace.rs
index 4a4996cf4..ad705c752 100644
--- a/crates/project_model/src/cargo_workspace.rs
+++ b/crates/project_model/src/cargo_workspace.rs
@@ -1,4 +1,4 @@
-//! FIXME: write short doc here
+//! See [`CargoWorkspace`].
 
 use std::path::PathBuf;
 use std::{convert::TryInto, ops, process::Command, sync::Arc};
@@ -12,10 +12,9 @@ use rustc_hash::FxHashMap;
 use serde::Deserialize;
 use serde_json::from_value;
 
-use crate::build_data::BuildDataConfig;
-use crate::utf8_stdout;
+use crate::{build_data::BuildDataConfig, utf8_stdout};
 
-/// `CargoWorkspace` represents the logical structure of, well, a Cargo
+/// [`CargoWorkspace`] represents the logical structure of, well, a Cargo
 /// workspace. It pretty closely mirrors `cargo metadata` output.
 ///
 /// Note that internally, rust analyzer uses a different structure:
diff --git a/crates/project_model/src/lib.rs b/crates/project_model/src/lib.rs
index a5b35ed95..8c6cf94c2 100644
--- a/crates/project_model/src/lib.rs
+++ b/crates/project_model/src/lib.rs
@@ -1,4 +1,19 @@
-//! FIXME: write short doc here
+//! In rust-analyzer, we maintain a strict separation between pure abstract
+//! semantic project model and a concrete model of a particular build system.
+//!
+//! Pure model is represented by the [`base_db::CrateGraph`] from another crate.
+//!
+//! In this crate, we are conserned with "real world" project models.
+//!
+//! Specifically, here we have a representation for a Cargo project
+//! ([`CargoWorkspace`]) and for manually specified layout ([`ProjectJson`]).
+//!
+//! Roughly, the things we do here are:
+//!
+//! * Project discovery (where's the relevant Cargo.toml for the current dir).
+//! * Custom build steps (`build.rs` code generation and compilation of
+//!   procedural macros).
+//! * Lowering of concrete model to a [`base_db::CrateGraph`]
 
 mod cargo_workspace;
 mod cfg_flag;
diff --git a/crates/project_model/src/project_json.rs b/crates/project_model/src/project_json.rs
index 41a2ac03e..e8f1aca61 100644
--- a/crates/project_model/src/project_json.rs
+++ b/crates/project_model/src/project_json.rs
@@ -1,4 +1,9 @@
-//! FIXME: write short doc here
+//! `rust-project.json` file format.
+//!
+//! This format is spiritually a serialization of [`base_db::CrateGraph`]. The
+//! idea here is that people who do not use Cargo, can instead teach their build
+//! system to generate `rust-project.json` which can be ingested by
+//! rust-analyzer.
 
 use std::path::PathBuf;