From 81ffe973ac265507419024048c166bbeef9aa275 Mon Sep 17 00:00:00 2001 From: Aleksey Kladov Date: Sat, 6 Jun 2020 19:54:41 +0200 Subject: Document certain invariants --- docs/dev/README.md | 27 +++++++++++++++++++++++++++ 1 file changed, 27 insertions(+) diff --git a/docs/dev/README.md b/docs/dev/README.md index 6f74d4223..903cb4055 100644 --- a/docs/dev/README.md +++ b/docs/dev/README.md @@ -241,6 +241,33 @@ struct Foo { For `.md` and `.adoc` files, prefer a sentence-per-line format, don't wrap lines. If the line is too long, you want to split the sentence in two :-) +# Architecture Invariants + +This section tries to document high-level design constraints, which are not +always obvious from the low-level code. + +## Incomplete syntax trees + +Syntax trees are by design incomplete and do not enforce well-formedness. +If ast method returns an `Option`, it *can* be `None` at runtime, even if this is forbidden by the grammar. + +## LSP indenpendence + +rust-analyzer is independent from LSP. +It provides features for a hypothetical perfect Rust-specific IDE client. +Internal representations are lowered to LSP in the `rust-analyzer` crate (the only crate which is allowed to use LSP types). + +## IDE/Compiler split + +There's a semi-hard split between "compiler" and "IDE", at the `ra_hir` crate. +Compiler derives new facts about source code. +It explicitly acknowledges that not all info is available (ie, you can't look at types during name resolution). + +IDE assumes that all information is available at all times. + +IDE should use only types from `ra_hir`, and should not depend on the underling compiler types. +`ra_hir` is a facade. + # Logging Logging is done by both rust-analyzer and VS Code, so it might be tricky to -- cgit v1.2.3