9 files changed, 14 insertions, 9 deletions

diff --git a/crates/ra_lsp_server/src/caps.rs b/crates/ra_lsp_server/src/caps.rs
index d812ff7ca..eeca67ee1 100644
--- a/crates/ra_lsp_server/src/caps.rs
+++ b/crates/ra_lsp_server/src/caps.rs
@@ -1,4 +1,4 @@
-//! FIXME: write short doc here
+//! Advertizes the capabilities of the LSP Server.
 
 use lsp_types::{
     CodeActionProviderCapability, CodeLensOptions, CompletionOptions,
diff --git a/crates/ra_lsp_server/src/conv.rs b/crates/ra_lsp_server/src/conv.rs
index 5561f6270..e93d4ea33 100644
--- a/crates/ra_lsp_server/src/conv.rs
+++ b/crates/ra_lsp_server/src/conv.rs
@@ -1,4 +1,4 @@
-//! FIXME: write short doc here
+//! Convenience module responsible for translating between rust-analyzer's types and LSP types.
 
 use lsp_types::{
     self, CreateFile, DiagnosticSeverity, DocumentChangeOperation, DocumentChanges, Documentation,
diff --git a/crates/ra_lsp_server/src/main_loop.rs b/crates/ra_lsp_server/src/main_loop.rs
index 9e207415e..81fd08c91 100644
--- a/crates/ra_lsp_server/src/main_loop.rs
+++ b/crates/ra_lsp_server/src/main_loop.rs
@@ -1,4 +1,5 @@
-//! FIXME: write short doc here
+//! The main loop of `ra_lsp_server` responsible for dispatching LSP requests/replies and
+//! notifications back to the client.
 
 mod handlers;
 mod subscriptions;
diff --git a/crates/ra_lsp_server/src/main_loop/handlers.rs b/crates/ra_lsp_server/src/main_loop/handlers.rs
index 5e3b1a73f..39eb3df3e 100644
--- a/crates/ra_lsp_server/src/main_loop/handlers.rs
+++ b/crates/ra_lsp_server/src/main_loop/handlers.rs
@@ -1,4 +1,5 @@
-//! FIXME: write short doc here
+//! This module is responsible for implementing handlers for Lanuage Server Protocol.
+//! The majority of requests are fulfilled by calling into the `ra_ide` crate.
 
 use std::{fmt::Write as _, io::Write as _};
 
diff --git a/crates/ra_lsp_server/src/main_loop/pending_requests.rs b/crates/ra_lsp_server/src/main_loop/pending_requests.rs
index e7ea7aa5b..2d2213464 100644
--- a/crates/ra_lsp_server/src/main_loop/pending_requests.rs
+++ b/crates/ra_lsp_server/src/main_loop/pending_requests.rs
@@ -1,4 +1,4 @@
-//! FIXME: write short doc here
+//! Datastructures that keep track of inflight requests.
 
 use std::time::{Duration, Instant};
 
diff --git a/crates/ra_lsp_server/src/main_loop/subscriptions.rs b/crates/ra_lsp_server/src/main_loop/subscriptions.rs
index 609b2adcc..b0bae90f5 100644
--- a/crates/ra_lsp_server/src/main_loop/subscriptions.rs
+++ b/crates/ra_lsp_server/src/main_loop/subscriptions.rs
@@ -1,4 +1,4 @@
-//! FIXME: write short doc here
+//! Keeps track of file subscriptions.
 
 use ra_ide::FileId;
 use rustc_hash::FxHashSet;
diff --git a/crates/ra_lsp_server/src/markdown.rs b/crates/ra_lsp_server/src/markdown.rs
index f51fc4ade..76bef45cc 100644
--- a/crates/ra_lsp_server/src/markdown.rs
+++ b/crates/ra_lsp_server/src/markdown.rs
@@ -1,4 +1,4 @@
-//! FIXME: write short doc here
+//! Transforms markdown
 
 pub(crate) fn format_docs(src: &str) -> String {
     let mut processed_lines = Vec::new();
diff --git a/crates/ra_lsp_server/src/req.rs b/crates/ra_lsp_server/src/req.rs
index 2a22b655c..b34e6f9b8 100644
--- a/crates/ra_lsp_server/src/req.rs
+++ b/crates/ra_lsp_server/src/req.rs
@@ -1,4 +1,4 @@
-//! FIXME: write short doc here
+//! Defines `rust-analyzer` specific custom messages.
 
 use lsp_types::{Location, Position, Range, TextDocumentIdentifier, Url};
 use rustc_hash::FxHashMap;
diff --git a/crates/ra_lsp_server/src/world.rs b/crates/ra_lsp_server/src/world.rs
index f89b23089..5e53b0278 100644
--- a/crates/ra_lsp_server/src/world.rs
+++ b/crates/ra_lsp_server/src/world.rs
@@ -1,4 +1,7 @@
-//! FIXME: write short doc here
+//! The context or environment in which the language server functions.
+//! In our server implementation this is know as the `WorldState`.
+//!
+//! Each tick provides an immutable snapshot of the state as `WorldSnapshot`.
 
 use std::{
     path::{Path, PathBuf},