Prepare gen_lsp_server for publishing

crates/gen_lsp_server/src/lib.rs

@@ -1,3 +1,65 @@
+//! A language server scaffold, exposing synchroneous crossbeam-channel based API.
+//! This crate handles protocol handshaking and parsing messages, while you
+//! control the message dispatch loop yourself.
+//!
+//! Run with `RUST_LOG=sync_lsp_server=debug` to see all the messages.
+//!
+//! ```no_run
+//! extern crate gen_lsp_server;
+//! extern crate languageserver_types;
+//! extern crate failure;
+//! extern crate crossbeam_channel;
+//!
+//! use crossbeam_channel::{Sender, Receiver};
+//! use languageserver_types::{ServerCapabilities, InitializeParams, request::{GotoDefinition, GotoDefinitionResponse}};
+//! use gen_lsp_server::{run_server, stdio_transport, handle_shutdown, RawMessage, RawResponse};
+//!
+//! fn main() -> Result<(), failure::Error> {
+//!     let (receiver, sender, io_threads) = stdio_transport();
+//!     gen_lsp_server::run_server(
+//!         ServerCapabilities::default(),
+//!         receiver,
+//!         sender,
+//!         main_loop,
+//!     )?;
+//!     io_threads.join()?;
+//!     Ok(())
+//! }
+//!
+//! fn main_loop(
+//!     _params: InitializeParams,
+//!     receiver: &Receiver<RawMessage>,
+//!     sender: &Sender<RawMessage>,
+//! ) -> Result<(), failure::Error> {
+//!     for msg in receiver {
+//!         match msg {
+//!             RawMessage::Request(req) => {
+//!                 let req = match handle_shutdown(req, sender) {
+//!                     None => return Ok(()),
+//!                     Some(req) => req,
+//!                 };
+//!                 let req = match req.cast::<GotoDefinition>() {
+//!                     Ok((id, _params)) => {
+//!                         let resp = RawResponse::ok::<GotoDefinition>(
+//!                             id,
+//!                             &Some(GotoDefinitionResponse::Array(Vec::new())),
+//!                         );
+//!                         sender.send(RawMessage::Response(resp));
+//!                         continue;
+//!                     },
+//!                     Err(req) => req,
+//!                 };
+//!                 // ...
+//!             }
+//!             RawMessage::Response(_resp) => (),
+//!             RawMessage::Notification(_not) => (),
+//!         }
+//!     }
+//!     Ok(())
+//! }
+//! ```
+
+
 #[macro_use]
 extern crate failure;
 #[macro_use]
@@ -25,20 +87,26 @@ pub use {
     stdio::{stdio_transport, Threads},
 };
 
+/// Main entry point: runs the server from initialization to shutdown.
+/// To attach server to standard input/output streams, use `stdio_transport`
+/// function to create corresponding `sender` and `receiver` pair.
+///
+///`server` should use `handle_shutdown` function to handle the `Shutdown`
+/// request.
 pub fn run_server(
     caps: ServerCapabilities,
+    receiver: Receiver<RawMessage>,
+    sender: Sender<RawMessage>,
     server: impl FnOnce(
         InitializeParams,
-        &mut Receiver<RawMessage>,
-        &mut Sender<RawMessage>,
+        &Receiver<RawMessage>,
+        &Sender<RawMessage>,
     ) -> Result<()>,
-    mut receiver: Receiver<RawMessage>,
-    mut sender: Sender<RawMessage>,
 ) -> Result<()> {
     info!("lsp server initializes");
-    let params = initialize(&mut receiver, &mut sender, caps)?;
+    let params = initialize(&receiver, &sender, caps)?;
     info!("lsp server initialized, serving requests");
-    server(params, &mut receiver, &mut sender)?;
+    server(params, &receiver, &sender)?;
     info!("lsp server waiting for exit notification");
     match receiver.recv() {
         Some(RawMessage::Notification(n)) => {
@@ -52,6 +120,7 @@ pub fn run_server(
     Ok(())
 }
 
+/// if `req` is `Shutdown`, respond to it and return `None`, otherwise return `Some(req)`
 pub fn handle_shutdown(req: RawRequest, sender: &Sender<RawMessage>) -> Option<RawRequest> {
     match req.cast::<Shutdown>() {
         Ok((id, ())) => {
@@ -64,8 +133,8 @@ pub fn handle_shutdown(req: RawRequest, sender: &Sender<RawMessage>) -> Option<R
 }
 
 fn initialize(
-    receiver: &mut Receiver<RawMessage>,
-    sender: &mut Sender<RawMessage>,
+    receiver: &Receiver<RawMessage>,
+    sender: &Sender<RawMessage>,
     caps: ServerCapabilities,
 ) -> Result<InitializeParams> {
     let (id, params) = match receiver.recv() {