diff --git a/crates/ra_lsp_server/src/cargo_target_spec.rs b/crates/ra_lsp_server/src/cargo_target_spec.rs
index d0a52670a1..53751aafb7 100644
--- a/crates/ra_lsp_server/src/cargo_target_spec.rs
+++ b/crates/ra_lsp_server/src/cargo_target_spec.rs
@@ -1,10 +1,14 @@
-//! FIXME: write short doc here
+//! See `CargoTargetSpec`
 
 use ra_ide::{FileId, RunnableKind, TestId};
 use ra_project_model::{self, ProjectWorkspace, TargetKind};
 
 use crate::{world::WorldSnapshot, Result};
 
+/// Abstract representation of Cargo target.
+///
+/// We use it to cook up the set of cli args we need to pass to Cargo to
+/// build/test/run the target.
 pub(crate) struct CargoTargetSpec {
     pub(crate) package: String,
     pub(crate) target: String,
diff --git a/crates/ra_lsp_server/src/conv.rs b/crates/ra_lsp_server/src/conv.rs
index 8af74b2112..90ef74056b 100644
--- a/crates/ra_lsp_server/src/conv.rs
+++ b/crates/ra_lsp_server/src/conv.rs
@@ -1,4 +1,5 @@
-//! Convenience module responsible for translating between rust-analyzer's types and LSP types.
+//! 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/diagnostics.rs b/crates/ra_lsp_server/src/diagnostics.rs
index ea08bce24b..e7924f0a30 100644
--- a/crates/ra_lsp_server/src/diagnostics.rs
+++ b/crates/ra_lsp_server/src/diagnostics.rs
@@ -1,7 +1,9 @@
 //! Book keeping for keeping diagnostics easily in sync with the client.
+
+use std::{collections::HashMap, sync::Arc};
+
 use lsp_types::{CodeActionOrCommand, Diagnostic, Range};
 use ra_ide::FileId;
-use std::{collections::HashMap, sync::Arc};
 
 pub type CheckFixes = Arc<HashMap<FileId, Vec<Fix>>>;
 
diff --git a/crates/ra_lsp_server/src/main_loop.rs b/crates/ra_lsp_server/src/main_loop.rs
index 944074118d..67d8a5f6fa 100644
--- a/crates/ra_lsp_server/src/main_loop.rs
+++ b/crates/ra_lsp_server/src/main_loop.rs
@@ -1,5 +1,5 @@
-//! The main loop of `ra_lsp_server` responsible for dispatching LSP requests/replies and
-//! notifications back to the client.
+//! 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 92f219e28d..bb7bab3729 100644
--- a/crates/ra_lsp_server/src/main_loop/handlers.rs
+++ b/crates/ra_lsp_server/src/main_loop/handlers.rs
@@ -1,5 +1,6 @@
-//! This module is responsible for implementing handlers for Lanuage Server Protocol.
-//! The majority of requests are fulfilled by calling into the `ra_ide` crate.
+//! This module is responsible for implementing handlers for Language Server
+//! Protocol. The majority of requests are fulfilled by calling into the
+//! `ra_ide` crate.
 
 use std::{
     collections::hash_map::Entry,
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 2d22134641..73b33e4194 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 @@
-//! Datastructures that keep track of inflight requests.
+//! Data structures 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 b0bae90f5c..bee6437cf3 100644
--- a/crates/ra_lsp_server/src/main_loop/subscriptions.rs
+++ b/crates/ra_lsp_server/src/main_loop/subscriptions.rs
@@ -1,4 +1,5 @@
-//! Keeps track of file subscriptions.
+//! Keeps track of file subscriptions -- the set of currently opened files for
+//! which we want to publish diagnostics, syntax highlighting, etc.
 
 use ra_ide::FileId;
 use rustc_hash::FxHashSet;
diff --git a/crates/ra_lsp_server/src/world.rs b/crates/ra_lsp_server/src/world.rs
index 71c95d4af0..96efab844d 100644
--- a/crates/ra_lsp_server/src/world.rs
+++ b/crates/ra_lsp_server/src/world.rs
@@ -1,5 +1,5 @@
-//! The context or environment in which the language server functions.
-//! In our server implementation this is know as the `WorldState`.
+//! 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`.