Merge #3264

3264: Tidy up documentation. r=flodiebold a=ablakey

Thought I'd tidy up the docs while reading through them. Hope you don't mind!

For the most part, I just made the formatting consistent through-out and added a few words here and there. Also updated the language server install graphic.

Co-authored-by: Andrew Blakey <[email protected]>

2 files changed, 24 insertions, 25 deletions

diff --git a/docs/user/features.md b/docs/user/features.md
index a00fa35da..f705e5115 100644
--- a/docs/user/features.md
+++ b/docs/user/features.md
@@ -1,10 +1,10 @@
-This documents is an index of features that rust-analyzer language server
+This document is an index of features that the rust-analyzer language server
 provides. Shortcuts are for the default VS Code layout. If there's no shortcut,
 you can use <kbd>Ctrl+Shift+P</kbd> to search for the corresponding action.
 
 ### Workspace Symbol <kbd>ctrl+t</kbd>
 
-Uses fuzzy-search to find types, modules and function by name across your
+Uses fuzzy-search to find types, modules and functions by name across your
 project and dependencies. This is **the** most useful feature, which improves code
 navigation tremendously. It mostly works on top of the built-in LSP
 functionality, however `#` and `*` symbols can be used to narrow down the
@@ -13,7 +13,7 @@ search. Specifically,
 - `Foo` searches for `Foo` type in the current workspace
 - `foo#` searches for `foo` function in the current workspace
 - `Foo*` searches for `Foo` type among dependencies, including `stdlib`
-- `foo#*` searches for `foo` function among dependencies.
+- `foo#*` searches for `foo` function among dependencies
 
 That is, `#` switches from "types" to all symbols, `*` switches from the current
 workspace to dependencies.
@@ -30,7 +30,7 @@ Provides a tree of the symbols defined in the file. Can be used to
 
 Some features trigger on typing certain characters:
 
-- typing `let =` tries to smartly add `;` if `=` is followed by an existing expression.
+- typing `let =` tries to smartly add `;` if `=` is followed by an existing expression
 - Enter inside comments automatically inserts `///`
 - typing `.` in a chain method call auto-indents
 
@@ -58,7 +58,7 @@ Navigates to the type of an identifier.
 
 #### Run
 
-Shows popup suggesting to run a test/benchmark/binary **at the current cursor
+Shows a popup suggesting to run a test/benchmark/binary **at the current cursor
 location**. Super useful for repeatedly running just a single test. Do bind this
 to a shortcut!
 
@@ -87,15 +87,15 @@ Shows the full macro expansion of the macro at current cursor.
 
 #### Status
 
-Shows internal statistic about memory usage of rust-analyzer
+Shows internal statistic about memory usage of rust-analyzer.
 
 #### Show RA Version
 
-Show current rust-analyzer version
+Show current rust-analyzer version.
 
-#### Run garbage collection
+#### Run Garbage Collection
 
-Manually triggers GC
+Manually triggers GC.
 
 #### Start Cargo Watch
 
@@ -103,7 +103,7 @@ Start `cargo watch` for live error highlighting. Will prompt to install if it's
 
 #### Stop Cargo Watch
 
-Stop `cargo watch`
+Stop `cargo watch`.
 
 ### Assists (Code Actions)
 
@@ -122,11 +122,11 @@ is placed at the appropriate position. Even though `if` is easy to type, you
 still want to complete it, to get ` { }` for free! `return` is inserted with a
 space or `;` depending on the return type of the function.
 
-When completing a function call, `()` are automatically inserted. If function
-takes arguments, cursor is positioned inside the parenthesis.
+When completing a function call, `()` are automatically inserted. If a function
+takes arguments, the cursor is positioned inside the parenthesis.
 
 There are postifx completions, which can be triggerd by typing something like
-`foo().if`. The word after `.` determines postifx completion, possible variants are:
+`foo().if`. The word after `.` determines postifx completion. Possible variants are:
 
 - `expr.if` -> `if expr {}`
 - `expr.match` -> `match expr {}`
@@ -147,12 +147,12 @@ There also snippet completions:
 
 - `tfn` -> `#[test] fn f(){}`
 
-### Code highlighting
+### Code Highlighting
 
 Experimental feature to let rust-analyzer highlight Rust code instead of using the
 default highlighter.
 
-#### Rainbow highlighting
+#### Rainbow Highlighting
 
 Experimental feature that, given code highlighting using rust-analyzer is
 active, will pick unique colors for identifiers.
diff --git a/docs/user/readme.adoc b/docs/user/readme.adoc
index 74fda0abe..f1386a8f9 100644
--- a/docs/user/readme.adoc
+++ b/docs/user/readme.adoc
@@ -6,10 +6,10 @@
 
 // Master copy of this document lives in the https://github.com/rust-analyzer/rust-analyzer repository
 
-At it's core, rust-analyzer is a *library* for semantic analysis of the Rust code as it changes over time.
+At its core, rust-analyzer is a *library* for semantic analysis of Rust code as it changes over time.
 This manual focuses on a specific usage of the library -- the implementation of
 https://microsoft.github.io/language-server-protocol/[Language Server Protocol].
-LSP allows various code editors, like VS Code, Emacs or Vim, to implement semantic feature like completion or goto definition by talking to an external language server process.
+LSP allows various code editors, like VS Code, Emacs or Vim, to implement semantic features like completion or goto definition by talking to an external language server process.
 
 To improve this document, send a pull request against
 https://github.com/rust-analyzer/rust-analyzer/blob/master/docs/user/readme.adoc[this file].
@@ -36,10 +36,9 @@ https://github.com/rust-analyzer/rust-analyzer/tree/master/editors/code[in tree]
 
 You can install the latest release of the plugin from
 https://marketplace.visualstudio.com/items?itemName=matklad.rust-analyzer[the marketplace].
-By default, the plugin will download the matching version of the server as well.
+By default, the plugin will prompt you to download the matching version of the server as well:
 
-// FIXME: update the image (its text has changed)
-image::https://user-images.githubusercontent.com/36276403/74103174-a40df100-4b52-11ea-81f4-372c70797924.png[]
+image::https://user-images.githubusercontent.com/9021944/75067008-17502500-54ba-11ea-835a-f92aac50e866.png[]
 
 The server binary is stored in `~/.config/Code/User/globalStorage/matklad.rust-analyzer`.
 
@@ -60,7 +59,7 @@ $ cargo xtask install
 ----
 
 You'll need Cargo, nodejs and npm for this.
-To make VS Code use the freshly build server, add this to the settings:
+To make VS Code use the freshly built server, add this to the settings:
 
 [source,json]
 ----
@@ -72,7 +71,7 @@ Note that installing via `xtask install` does not work for VS Code Remote, inste
 === Language Server Binary
 
 Other editors generally require `rust-analyzer` binary to be in `$PATH`.
-You can download pre-build binary from
+You can download the pre-built binary from
 https://github.com/rust-analyzer/rust-analyzer/releases[releases]
 page, or you can install it from source using the following command:
 
@@ -85,7 +84,7 @@ $ cargo xtask install --server
 
 Emacs support is maintained https://github.com/emacs-lsp/lsp-mode/blob/master/lsp-rust.el[upstream].
 
-1. Install recent version of `emacs-lsp` package by following the instructions https://github.com/emacs-lsp/lsp-mode[here].
+1. Install the most recent version of `emacs-lsp` package by following the instructions https://github.com/emacs-lsp/lsp-mode[here].
 2. Set `lsp-rust-server` to `'rust-analyzer`.
 3. Run `lsp` in a Rust buffer.
 4. (Optionally) bind commands like `lsp-rust-analyzer-join-lines`, `lsp-extend-selection` and `lsp-rust-analyzer-expand-macro` to keys.
@@ -112,7 +111,7 @@ The are several LSP client implementations for vim:
    https://github.com/autozimu/LanguageClient-neovim[here]
    * The github project wiki has extra tips on configuration
 
-2. Configure by adding this to your vim/neovim config file (replacing the existing rust specific line if it exists):
+2. Configure by adding this to your vim/neovim config file (replacing the existing Rust-specific line if it exists):
 +
 [source,vim]
 ----
@@ -123,7 +122,7 @@ let g:LanguageClient_serverCommands = {
 
 ==== nvim-lsp
 
-NeoVim 0.5 (not yet released) has built in language server support.
+NeoVim 0.5 (not yet released) has built-in language server support.
 For a quick start configuration of rust-analyzer, use https://github.com/neovim/nvim-lsp#rust_analyzer[neovim/nvim-lsp].
 Once `neovim/nvim-lsp` is installed, use `lua require'nvim_lsp'.rust_analyzer.setup({})` in your `init.vim`.