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: 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(-)

(limited to 'crates')

diff --git a/crates/ra_lsp_server/src/cargo_target_spec.rs b/crates/ra_lsp_server/src/cargo_target_spec.rs
index d0a52670a..53751aafb 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 8af74b211..90ef74056 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 ea08bce24..e7924f0a3 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 944074118..67d8a5f6f 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 92f219e28..bb7bab372 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 2d2213464..73b33e419 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 b0bae90f5..bee6437cf 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 71c95d4af..96efab844 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`.
 
-- 
cgit v1.2.3