From 0fc21bd303e89986f3bf17fd4b4b2786793a3fce Mon Sep 17 00:00:00 2001 From: veetaha Date: Mon, 23 Mar 2020 14:00:51 +0200 Subject: [PATCH] ra_hir: add more docs --- crates/ra_hir/src/lib.rs | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/crates/ra_hir/src/lib.rs b/crates/ra_hir/src/lib.rs index 9f59d590ce..585217b7c4 100644 --- a/crates/ra_hir/src/lib.rs +++ b/crates/ra_hir/src/lib.rs @@ -4,6 +4,18 @@ //! The principal difference between HIR and syntax trees is that HIR is bound //! to a particular crate instance. That is, it has cfg flags and features //! applied. So, the relation between syntax and HIR is many-to-one. +//! +//! HIR is the public API of the all of the compiler logic above syntax trees. +//! It is written in "OO" style. Each type is self contained (as in, it knows it's +//! parents and full context). It should be "clean code". +//! +//! `ra_hir_*` crates are the implementation of the compiler logic. +//! They are written in "ECS" style, with relatively little abstractions. +//! Many types are not self-contained, and explicitelly use local indexes, arenas, etc. +//! +//! `ra_hir` is what insulates the "we don't know how to actually write an incremental compiler" +//! from the ide with completions, hovers, etc. It is a (soft, internal) boundary: +//! https://www.tedinski.com/2018/02/06/system-boundaries.html. #![recursion_limit = "512"]