From 00e9d8335c6faa5923ca1bd6bfdef4b4da4d9ee6 Mon Sep 17 00:00:00 2001
From: Henrik Lissner <henrik@lissner.net>
Date: Sun, 23 Aug 2020 17:26:33 -0400
Subject: [PATCH] lang/rust: update readme

---
 modules/lang/rust/README.org | 68 ++++++++++++++++++++----------------
 1 file changed, 38 insertions(+), 30 deletions(-)

diff --git a/modules/lang/rust/README.org b/modules/lang/rust/README.org
index 4b31c8c9a..b902012a0 100644
--- a/modules/lang/rust/README.org
+++ b/modules/lang/rust/README.org
@@ -10,9 +10,11 @@
   - [[#hacks][Hacks]]
 - [[#prerequisites][Prerequisites]]
 - [[#features][Features]]
+  - [[#lsp-support-rls-or-rust-analyzer][LSP support (rls or rust-analyzer)]]
+  - [[#format-on-save][Format on save]]
   - [[#keybinds][Keybinds]]
 - [[#configuration][Configuration]]
-  - [[#enable-rust-analyzer][Enable rust-analyzer]]
+  - [[#enable-rls-by-default][Enable RLS by default]]
   - [[#enabling-elgot-support-for-rust][Enabling elgot support for Rust]]
 - [[#troubleshooting][Troubleshooting]]
 
@@ -20,13 +22,14 @@
 This module adds support for the Rust language and integration for its tools,
 e.g. ~cargo~.
 
-+ Code completion (~racer~)
-+ Syntax checking (~flycheck~)
-+ LSP support (for rls and rust-analyzer) (~rustic~)
++ Code completion (=racer= or an LSP server)
++ Syntax checking (=flycheck=)
++ LSP support (for rust-analyzer and rls) (=rustic=)
 + Snippets
 
 ** Module Flags
-+ ~+lsp~ to add support Language server protocol.
++ ~+lsp~ to add support Language server protocol. Will use the first of
+  =rust-analyzer= or =rls= (in that order).
 
 ** Plugins
 + [[https://github.com/brotzeit/rustic][rustic]]
@@ -34,28 +37,38 @@ e.g. ~cargo~.
 
 ** Hacks
 + rustic has been modified /not/ to automatically install lsp-mode or elgot if
-  they're missing. Doom expects you to enable the =:tools lsp= module yourself.
-+ rustic's LSP integration has been disabled in favor of the rls/rust-analyzer
-  support provider by the lsp-mode package.
+  they're missing. Doom expects you to have enabled the =:tools lsp= module
+  yourself.
 
 * Prerequisites
-This module only requires ~rust~, which can be acquired through =rustup=:
+This module requires ~rust~, which can be acquired through =rustup=:
 
 ~curl https://sh.rustup.rs -sSf | sh~
 
-Optionally, this module also uses the following programs:
+Additional requirements depend on the module's configuration:
 
-+ =racer= (if not using LSP): ~cargo +nightly install racer~ (requires rust nightly)
-+ =RLS= or =rust-analyzer= (for LSP users)
-+ =rustfmt= for ~:editor format~: ~rustup component add rustfmt-preview~
-+ The following commands require:
++ If =:editor format= is enabled, you'll need =rustfmt=: ~rustup component add
+  rustfmt-preview~.
++ Users without =+lsp= enabled will need =racer=: ~cargo +nightly install racer~
+  (with requires rust nightly edition).
++ Users with =+lsp= enabled will need:
+  + =rust-analyzer= or =rls=
++ To use The following commands require:
   + ~cargo-process-check~: ~cargo install cargo-check~
   + ~cargo-process-clippy~: ~rustup component add clippy-preview~
 
 * Features
-This module also supports LSP, if you have [[https://github.com/rust-lang/rls][the Rust Language Server]] or
-[[https://github.com/rust-analyzer/rust-analyzer][rust-analyzer]] installed. To enable it, you must enable the =:tools lsp= module
-and the ~+lsp~ flag on this module.
+** LSP support (rls or rust-analyzer)
+This module supports LSP integration. For it to work you'll need:
+
+1. Either [[https://github.com/rust-analyzer/rust-analyzer][rust-analyzer]] or [[https://github.com/rust-lang/rls][the Rust Language Server]] installed (e.g. through your
+   OS package manager).
+2. The =:tools lsp= module enabled.
+3. The ~+lsp~ flag on this module enabled.
+
+** Format on save
+Enable the [[file:../../../modules/editor/format/README.org][:editor format]] module's =+onsave= flag to get formatting on save with
+rustfmt. No additional configuration is necessary.
 
 ** Keybinds
 | Binding             | Description                 |
@@ -73,23 +86,18 @@ and the ~+lsp~ flag on this module.
 | ~<localleader> t t~ | ~run current test~          |
 
 * TODO Configuration
-** Enable rust-analyzer
-You'll need [[https://github.com/rust-analyzer/rust-analyzer][rust-analyzer]] installed on your system, then use the following:
-
-#+BEGIN_SRC elisp
-;; in $DOOMDIR/config.el
-(setq rustic-lsp-server 'rust-analyzer)
-#+END_SRC
-
-** Enabling elgot support for Rust
-Doom doesn't have eglot support (yet), but if you've installed it yourself and
-want rust to use eglot instead of LSP, use the following:
+** Enable RLS by default
+If both =rls= and =rust-analyzer= are present on your system, =rust-analyzer= is
+selected by default. Modify ~rustic-lsp-server~ to change the default:
 
 #+BEGIN_SRC elisp
 ;; in $DOOMDIR/config.el
 (after! rustic
-  (setq rustic-lsp-server 'rust-analyzer ; optional
-        rustic-lsp-client 'eglot))
+  (setq rustic-lsp-server 'rls))
 #+END_SRC
 
+** Enabling elgot support for Rust
+Doom's =:tools lsp= module has an =+eglot= flag. Enable it and this module will
+use eglot instead.
+
 * TODO Troubleshooting