document design guideline

diff --git a/crates/ra_ide_api/src/lib.rs b/crates/ra_ide_api/src/lib.rs
index d77a56ce805c23a5aa2fe9b42b70271cff0309b1..1746b58aeafa34dcdc217eed2d663ccd5a24b88e 100644 (file)
--- a/crates/ra_ide_api/src/lib.rs
+++ b/crates/ra_ide_api/src/lib.rs
@@ -200,6 +200,12 @@ pub struct Analysis {
     db: salsa::Snapshot<db::RootDatabase>,
 }
 
+// As a general design guideline, `Analysis` API are intended to be independent
+// from the language server protocol. That is, when exposing some functionality
+// we should think in terms of "what API makes most sense" and not in terms of
+// "what types LSP uses". Although currently LSP is the only consumer of the
+// API, the API should in theory be usable as a library, or via a different
+// protocol.
 impl Analysis {
     /// Debug info about the current state of the analysis
     pub fn status(&self) -> String {