From 188b0f96f98feaa0771f941343887c46113c8ced Mon Sep 17 00:00:00 2001 From: Aleksey Kladov Date: Sat, 22 May 2021 16:53:47 +0300 Subject: Add more docs --- crates/project_model/src/cargo_workspace.rs | 7 +++---- crates/project_model/src/lib.rs | 17 ++++++++++++++++- crates/project_model/src/project_json.rs | 7 ++++++- 3 files changed, 25 insertions(+), 6 deletions(-) (limited to 'crates/project_model/src') 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; -- cgit v1.2.3