From 59e1207dac8eb9cc56a72ee685bd4f143683d2bb Mon Sep 17 00:00:00 2001
From: Aleksey Kladov <aleksey.kladov@gmail.com>
Date: Tue, 18 Feb 2020 11:56:18 +0100
Subject: [PATCH 1/6] Better folder structure

---
 crates/ra_lsp_server/Cargo.toml            | 5 +++++
 crates/ra_lsp_server/src/{ => bin}/args.rs | 0
 crates/ra_lsp_server/src/{ => bin}/main.rs | 0
 xtask/tests/tidy-tests/docs.rs             | 1 -
 4 files changed, 5 insertions(+), 1 deletion(-)
 rename crates/ra_lsp_server/src/{ => bin}/args.rs (100%)
 rename crates/ra_lsp_server/src/{ => bin}/main.rs (100%)

diff --git a/crates/ra_lsp_server/Cargo.toml b/crates/ra_lsp_server/Cargo.toml
index da523ba8a2..151ca3da51 100644
--- a/crates/ra_lsp_server/Cargo.toml
+++ b/crates/ra_lsp_server/Cargo.toml
@@ -3,10 +3,15 @@ edition = "2018"
 name = "ra_lsp_server"
 version = "0.1.0"
 authors = ["rust-analyzer developers"]
+autobins = false
 
 [lib]
 doctest = false
 
+[[bin]]
+name = "ra_lsp_server"
+path = "./src/bin/main.rs"
+
 [dependencies]
 anyhow = "1.0"
 crossbeam-channel = "0.4"
diff --git a/crates/ra_lsp_server/src/args.rs b/crates/ra_lsp_server/src/bin/args.rs
similarity index 100%
rename from crates/ra_lsp_server/src/args.rs
rename to crates/ra_lsp_server/src/bin/args.rs
diff --git a/crates/ra_lsp_server/src/main.rs b/crates/ra_lsp_server/src/bin/main.rs
similarity index 100%
rename from crates/ra_lsp_server/src/main.rs
rename to crates/ra_lsp_server/src/bin/main.rs
diff --git a/xtask/tests/tidy-tests/docs.rs b/xtask/tests/tidy-tests/docs.rs
index b2571df258..62c4f84413 100644
--- a/xtask/tests/tidy-tests/docs.rs
+++ b/xtask/tests/tidy-tests/docs.rs
@@ -77,7 +77,6 @@ fn no_docs_comments() {
         "ra_hir",
         "ra_hir_expand",
         "ra_ide",
-        "ra_lsp_server",
         "ra_mbe",
         "ra_parser",
         "ra_prof",

From 93b969003d0a9448d4207d9d5df9dde63f9444be Mon Sep 17 00:00:00 2001
From: Aleksey Kladov <aleksey.kladov@gmail.com>
Date: Tue, 18 Feb 2020 12:11:32 +0100
Subject: [PATCH 2/6] Some docs

---
 crates/ra_lsp_server/src/bin/main.rs           |  4 +++-
 crates/ra_lsp_server/src/cli.rs                |  2 +-
 crates/ra_lsp_server/src/cli/analysis_bench.rs |  2 +-
 crates/ra_lsp_server/src/cli/analysis_stats.rs |  3 ++-
 crates/ra_lsp_server/src/cli/load_cargo.rs     | 18 ++++++++++--------
 crates/ra_lsp_server/src/lib.rs                |  7 +++++--
 crates/ra_lsp_server/src/vfs_glob.rs           |  2 +-
 7 files changed, 23 insertions(+), 15 deletions(-)

diff --git a/crates/ra_lsp_server/src/bin/main.rs b/crates/ra_lsp_server/src/bin/main.rs
index a549e5ff12..e25d54a0d6 100644
--- a/crates/ra_lsp_server/src/bin/main.rs
+++ b/crates/ra_lsp_server/src/bin/main.rs
@@ -1,4 +1,6 @@
-//! `ra_lsp_server` binary
+//! Driver for rust-analyzer.
+//!
+//! Based on cli flags, either spawns an LSP server, or runs a batch analysis
 mod args;
 
 use lsp_server::Connection;
diff --git a/crates/ra_lsp_server/src/cli.rs b/crates/ra_lsp_server/src/cli.rs
index 3c7b8e2509..c9738d1010 100644
--- a/crates/ra_lsp_server/src/cli.rs
+++ b/crates/ra_lsp_server/src/cli.rs
@@ -1,4 +1,4 @@
-//! FIXME: write short doc here
+//! Various batch processing tasks, intended primarily for debugging.
 
 mod load_cargo;
 mod analysis_stats;
diff --git a/crates/ra_lsp_server/src/cli/analysis_bench.rs b/crates/ra_lsp_server/src/cli/analysis_bench.rs
index e00f810734..91855e5925 100644
--- a/crates/ra_lsp_server/src/cli/analysis_bench.rs
+++ b/crates/ra_lsp_server/src/cli/analysis_bench.rs
@@ -1,4 +1,4 @@
-//! FIXME: write short doc here
+//! Benchmark operations like highlighting or goto definition.
 
 use std::{
     path::{Path, PathBuf},
diff --git a/crates/ra_lsp_server/src/cli/analysis_stats.rs b/crates/ra_lsp_server/src/cli/analysis_stats.rs
index c27fabe3c4..99ab6e4437 100644
--- a/crates/ra_lsp_server/src/cli/analysis_stats.rs
+++ b/crates/ra_lsp_server/src/cli/analysis_stats.rs
@@ -1,4 +1,5 @@
-//! FIXME: write short doc here
+//! Fully type-check project and print various stats, like the number of type
+//! errors.
 
 use std::{collections::HashSet, fmt::Write, path::Path, time::Instant};
 
diff --git a/crates/ra_lsp_server/src/cli/load_cargo.rs b/crates/ra_lsp_server/src/cli/load_cargo.rs
index bb3e1513b8..8cd08ecb6f 100644
--- a/crates/ra_lsp_server/src/cli/load_cargo.rs
+++ b/crates/ra_lsp_server/src/cli/load_cargo.rs
@@ -1,18 +1,18 @@
-//! FIXME: write short doc here
+//! Loads a Cargo project into a static instance of analysis, without support
+//! for incorporating changes.
 
-use std::{collections::HashSet, path::Path};
+use std::path::Path;
 
+use anyhow::Result;
 use crossbeam_channel::{unbounded, Receiver};
 use ra_db::{CrateGraph, FileId, SourceRootId};
 use ra_ide::{AnalysisChange, AnalysisHost, FeatureFlags};
 use ra_project_model::{get_rustc_cfg_options, PackageRoot, ProjectWorkspace};
 use ra_vfs::{RootEntry, Vfs, VfsChange, VfsTask, Watch};
-use rustc_hash::FxHashMap;
+use rustc_hash::{FxHashMap, FxHashSet};
 
 use crate::vfs_glob::RustPackageFilterBuilder;
 
-use anyhow::Result;
-
 fn vfs_file_to_id(f: ra_vfs::VfsFile) -> FileId {
     FileId(f.0)
 }
@@ -20,7 +20,9 @@ fn vfs_root_to_id(r: ra_vfs::VfsRoot) -> SourceRootId {
     SourceRootId(r.0)
 }
 
-pub fn load_cargo(root: &Path) -> Result<(AnalysisHost, FxHashMap<SourceRootId, PackageRoot>)> {
+pub(crate) fn load_cargo(
+    root: &Path,
+) -> Result<(AnalysisHost, FxHashMap<SourceRootId, PackageRoot>)> {
     let root = std::env::current_dir()?.join(root);
     let ws = ProjectWorkspace::discover(root.as_ref(), &Default::default())?;
     let project_roots = ws.to_roots();
@@ -74,7 +76,7 @@ pub fn load_cargo(root: &Path) -> Result<(AnalysisHost, FxHashMap<SourceRootId,
     Ok((host, source_roots))
 }
 
-pub fn load(
+pub(crate) fn load(
     source_roots: &FxHashMap<SourceRootId, PackageRoot>,
     crate_graph: CrateGraph,
     vfs: &mut Vfs,
@@ -86,7 +88,7 @@ pub fn load(
     analysis_change.set_crate_graph(crate_graph);
 
     // wait until Vfs has loaded all roots
-    let mut roots_loaded = HashSet::new();
+    let mut roots_loaded = FxHashSet::default();
     for task in receiver {
         vfs.handle_task(task);
         let mut done = false;
diff --git a/crates/ra_lsp_server/src/lib.rs b/crates/ra_lsp_server/src/lib.rs
index 958c70fe5f..0dae30e46e 100644
--- a/crates/ra_lsp_server/src/lib.rs
+++ b/crates/ra_lsp_server/src/lib.rs
@@ -1,10 +1,13 @@
 //! Implementation of the LSP for rust-analyzer.
 //!
-//! This crate takes Rust-specific analysis results from ra_ide and
-//! translates into LSP types.
+//! This crate takes Rust-specific analysis results from ra_ide and translates
+//! into LSP types.
 //!
 //! It also is the root of all state. `world` module defines the bulk of the
 //! state, and `main_loop` module defines the rules for modifying it.
+//!
+//! The `cli` submodule implements some batch-processing analysis, primarily as
+//! a debugging aid.
 #![recursion_limit = "512"]
 
 pub mod cli;
diff --git a/crates/ra_lsp_server/src/vfs_glob.rs b/crates/ra_lsp_server/src/vfs_glob.rs
index 12401d75a8..91b33f94e8 100644
--- a/crates/ra_lsp_server/src/vfs_glob.rs
+++ b/crates/ra_lsp_server/src/vfs_glob.rs
@@ -1,4 +1,4 @@
-//! `ra_vfs_glob` crate implements exclusion rules for vfs.
+//! Exclusion rules for vfs.
 //!
 //! By default, we include only `.rs` files, and skip some know offenders like
 //! `/target` or `/node_modules` altogether.

From b6740060f60fa016ac1c3d420c9ac919d31f6997 Mon Sep 17 00:00:00 2001
From: Aleksey Kladov <aleksey.kladov@gmail.com>
Date: Tue, 18 Feb 2020 12:15:12 +0100
Subject: [PATCH 3/6] Refactor

---
 crates/ra_lsp_server/src/cargo_target_spec.rs  | 4 +---
 crates/ra_lsp_server/src/main_loop/handlers.rs | 3 ++-
 2 files changed, 3 insertions(+), 4 deletions(-)

diff --git a/crates/ra_lsp_server/src/cargo_target_spec.rs b/crates/ra_lsp_server/src/cargo_target_spec.rs
index 5fd1e7b6b3..56d3f0de45 100644
--- a/crates/ra_lsp_server/src/cargo_target_spec.rs
+++ b/crates/ra_lsp_server/src/cargo_target_spec.rs
@@ -6,11 +6,9 @@ use ra_project_model::{self, ProjectWorkspace, TargetKind};
 use crate::{world::WorldSnapshot, Result};
 
 pub(crate) fn runnable_args(
-    world: &WorldSnapshot,
-    file_id: FileId,
+    spec: Option<CargoTargetSpec>,
     kind: &RunnableKind,
 ) -> Result<Vec<String>> {
-    let spec = CargoTargetSpec::for_file(world, file_id)?;
     let mut res = Vec::new();
     match kind {
         RunnableKind::Test { test_id } => {
diff --git a/crates/ra_lsp_server/src/main_loop/handlers.rs b/crates/ra_lsp_server/src/main_loop/handlers.rs
index ae51141cbf..833f31d961 100644
--- a/crates/ra_lsp_server/src/main_loop/handlers.rs
+++ b/crates/ra_lsp_server/src/main_loop/handlers.rs
@@ -921,7 +921,8 @@ fn to_lsp_runnable(
     file_id: FileId,
     runnable: Runnable,
 ) -> Result<req::Runnable> {
-    let args = runnable_args(world, file_id, &runnable.kind)?;
+    let spec: Option<CargoTargetSpec> = CargoTargetSpec::for_file(world, file_id)?;
+    let args = runnable_args(spec, &runnable.kind)?;
     let line_index = world.analysis().file_line_index(file_id)?;
     let label = match &runnable.kind {
         RunnableKind::Test { test_id } => format!("test {}", test_id),

From 42c766b2bdb88afbde051db064f255aa71c75fbd Mon Sep 17 00:00:00 2001
From: Aleksey Kladov <aleksey.kladov@gmail.com>
Date: Tue, 18 Feb 2020 12:16:40 +0100
Subject: [PATCH 4/6] Reduce visibility

---
 crates/ra_lsp_server/src/cargo_target_spec.rs | 15 +++++++++------
 1 file changed, 9 insertions(+), 6 deletions(-)

diff --git a/crates/ra_lsp_server/src/cargo_target_spec.rs b/crates/ra_lsp_server/src/cargo_target_spec.rs
index 56d3f0de45..e08cc30e2e 100644
--- a/crates/ra_lsp_server/src/cargo_target_spec.rs
+++ b/crates/ra_lsp_server/src/cargo_target_spec.rs
@@ -54,14 +54,17 @@ pub(crate) fn runnable_args(
     Ok(res)
 }
 
-pub struct CargoTargetSpec {
-    pub package: String,
-    pub target: String,
-    pub target_kind: TargetKind,
+pub(crate) struct CargoTargetSpec {
+    pub(crate) package: String,
+    pub(crate) target: String,
+    pub(crate) target_kind: TargetKind,
 }
 
 impl CargoTargetSpec {
-    pub fn for_file(world: &WorldSnapshot, file_id: FileId) -> Result<Option<CargoTargetSpec>> {
+    pub(crate) fn for_file(
+        world: &WorldSnapshot,
+        file_id: FileId,
+    ) -> Result<Option<CargoTargetSpec>> {
         let &crate_id = match world.analysis().crate_for(file_id)?.first() {
             Some(crate_id) => crate_id,
             None => return Ok(None),
@@ -82,7 +85,7 @@ impl CargoTargetSpec {
         Ok(res)
     }
 
-    pub fn push_to(self, buf: &mut Vec<String>) {
+    pub(crate) fn push_to(self, buf: &mut Vec<String>) {
         buf.push("--package".to_string());
         buf.push(self.package);
         match self.target_kind {

From 1f142d79ed251db58570a5863b06c8826221f9c9 Mon Sep 17 00:00:00 2001
From: Aleksey Kladov <aleksey.kladov@gmail.com>
Date: Tue, 18 Feb 2020 12:17:47 +0100
Subject: [PATCH 5/6] Refactor

---
 crates/ra_lsp_server/src/cargo_target_spec.rs | 98 +++++++++----------
 .../ra_lsp_server/src/main_loop/handlers.rs   |  6 +-
 2 files changed, 52 insertions(+), 52 deletions(-)

diff --git a/crates/ra_lsp_server/src/cargo_target_spec.rs b/crates/ra_lsp_server/src/cargo_target_spec.rs
index e08cc30e2e..d0a52670a1 100644
--- a/crates/ra_lsp_server/src/cargo_target_spec.rs
+++ b/crates/ra_lsp_server/src/cargo_target_spec.rs
@@ -5,55 +5,6 @@ use ra_project_model::{self, ProjectWorkspace, TargetKind};
 
 use crate::{world::WorldSnapshot, Result};
 
-pub(crate) fn runnable_args(
-    spec: Option<CargoTargetSpec>,
-    kind: &RunnableKind,
-) -> Result<Vec<String>> {
-    let mut res = Vec::new();
-    match kind {
-        RunnableKind::Test { test_id } => {
-            res.push("test".to_string());
-            if let Some(spec) = spec {
-                spec.push_to(&mut res);
-            }
-            res.push("--".to_string());
-            res.push(test_id.to_string());
-            if let TestId::Path(_) = test_id {
-                res.push("--exact".to_string());
-            }
-            res.push("--nocapture".to_string());
-        }
-        RunnableKind::TestMod { path } => {
-            res.push("test".to_string());
-            if let Some(spec) = spec {
-                spec.push_to(&mut res);
-            }
-            res.push("--".to_string());
-            res.push(path.to_string());
-            res.push("--nocapture".to_string());
-        }
-        RunnableKind::Bench { test_id } => {
-            res.push("bench".to_string());
-            if let Some(spec) = spec {
-                spec.push_to(&mut res);
-            }
-            res.push("--".to_string());
-            res.push(test_id.to_string());
-            if let TestId::Path(_) = test_id {
-                res.push("--exact".to_string());
-            }
-            res.push("--nocapture".to_string());
-        }
-        RunnableKind::Bin => {
-            res.push("run".to_string());
-            if let Some(spec) = spec {
-                spec.push_to(&mut res);
-            }
-        }
-    }
-    Ok(res)
-}
-
 pub(crate) struct CargoTargetSpec {
     pub(crate) package: String,
     pub(crate) target: String,
@@ -61,6 +12,55 @@ pub(crate) struct CargoTargetSpec {
 }
 
 impl CargoTargetSpec {
+    pub(crate) fn runnable_args(
+        spec: Option<CargoTargetSpec>,
+        kind: &RunnableKind,
+    ) -> Result<Vec<String>> {
+        let mut res = Vec::new();
+        match kind {
+            RunnableKind::Test { test_id } => {
+                res.push("test".to_string());
+                if let Some(spec) = spec {
+                    spec.push_to(&mut res);
+                }
+                res.push("--".to_string());
+                res.push(test_id.to_string());
+                if let TestId::Path(_) = test_id {
+                    res.push("--exact".to_string());
+                }
+                res.push("--nocapture".to_string());
+            }
+            RunnableKind::TestMod { path } => {
+                res.push("test".to_string());
+                if let Some(spec) = spec {
+                    spec.push_to(&mut res);
+                }
+                res.push("--".to_string());
+                res.push(path.to_string());
+                res.push("--nocapture".to_string());
+            }
+            RunnableKind::Bench { test_id } => {
+                res.push("bench".to_string());
+                if let Some(spec) = spec {
+                    spec.push_to(&mut res);
+                }
+                res.push("--".to_string());
+                res.push(test_id.to_string());
+                if let TestId::Path(_) = test_id {
+                    res.push("--exact".to_string());
+                }
+                res.push("--nocapture".to_string());
+            }
+            RunnableKind::Bin => {
+                res.push("run".to_string());
+                if let Some(spec) = spec {
+                    spec.push_to(&mut res);
+                }
+            }
+        }
+        Ok(res)
+    }
+
     pub(crate) fn for_file(
         world: &WorldSnapshot,
         file_id: FileId,
diff --git a/crates/ra_lsp_server/src/main_loop/handlers.rs b/crates/ra_lsp_server/src/main_loop/handlers.rs
index 833f31d961..92f219e28d 100644
--- a/crates/ra_lsp_server/src/main_loop/handlers.rs
+++ b/crates/ra_lsp_server/src/main_loop/handlers.rs
@@ -29,7 +29,7 @@ use serde::{Deserialize, Serialize};
 use serde_json::to_value;
 
 use crate::{
-    cargo_target_spec::{runnable_args, CargoTargetSpec},
+    cargo_target_spec::CargoTargetSpec,
     conv::{
         to_call_hierarchy_item, to_location, Conv, ConvWith, FoldConvCtx, MapConvWith, TryConvWith,
         TryConvWithToVec,
@@ -921,8 +921,8 @@ fn to_lsp_runnable(
     file_id: FileId,
     runnable: Runnable,
 ) -> Result<req::Runnable> {
-    let spec: Option<CargoTargetSpec> = CargoTargetSpec::for_file(world, file_id)?;
-    let args = runnable_args(spec, &runnable.kind)?;
+    let spec = CargoTargetSpec::for_file(world, file_id)?;
+    let args = CargoTargetSpec::runnable_args(spec, &runnable.kind)?;
     let line_index = world.analysis().file_line_index(file_id)?;
     let label = match &runnable.kind {
         RunnableKind::Test { test_id } => format!("test {}", test_id),

From 4d307ff8024c8d2d533bc3ab7aac1d63ca5c5977 Mon Sep 17 00:00:00 2001
From: Aleksey Kladov <aleksey.kladov@gmail.com>
Date: Tue, 18 Feb 2020 12:25:26 +0100
Subject: [PATCH 6/6] Fully document ra_lsp_server

---
 crates/ra_lsp_server/src/cargo_target_spec.rs          | 6 +++++-
 crates/ra_lsp_server/src/conv.rs                       | 3 ++-
 crates/ra_lsp_server/src/diagnostics.rs                | 4 +++-
 crates/ra_lsp_server/src/main_loop.rs                  | 4 ++--
 crates/ra_lsp_server/src/main_loop/handlers.rs         | 5 +++--
 crates/ra_lsp_server/src/main_loop/pending_requests.rs | 2 +-
 crates/ra_lsp_server/src/main_loop/subscriptions.rs    | 3 ++-
 crates/ra_lsp_server/src/world.rs                      | 4 ++--
 8 files changed, 20 insertions(+), 11 deletions(-)

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`.