Merge #1000

1000: Clean up some documentation debt r=Xanewok a=matklad



Co-authored-by: Aleksey Kladov <[email protected]>
Co-authored-by: bjorn3 <[email protected]>

2 files changed, 436 insertions, 0 deletions

diff --git a/docs/user/README.md b/docs/user/README.md
new file mode 100644
index 000000000..439c4e6ae
--- /dev/null
+++ b/docs/user/README.md
@@ -0,0 +1,77 @@
+The main interface to rust-analyzer is the
+[LSP](https://microsoft.github.io/language-server-protocol/) implementation. To
+install lsp server, use `cargo install-lsp`, which is a shorthand for `cargo
+install --package ra_lsp_server`. The binary is named `ra_lsp_server`, you
+should be able to use it with any LSP-compatible editor. We use custom
+extensions to LSP, so special client-side support is required to take full
+advantage of rust-analyzer. This repository contains support code for VS Code
+and Emacs.
+
+Rust Analyzer needs sources of rust standard library to work, so you might need
+to execute
+
+```
+$ rustup component add rust-src
+```
+
+See [./features.md](./features.md) document for a list of features that are available.
+
+## VS Code
+
+Prerequisites:
+
+In order to build the VS Code plugin, you need to have node.js and npm with
+a minimum version of 10 installed. Please refer to
+[node.js and npm documentation](https://nodejs.org) for installation instructions.
+
+You will also need the most recent version of VS Code: we don't try to
+maintain compatibility with older versions yet.
+
+The experimental VS Code plugin can then be built and installed by executing the
+following commands:
+
+```
+$ git clone https://github.com/rust-analyzer/rust-analyzer.git --depth 1
+$ cd rust-analyzer
+$ cargo install-code
+```
+
+This will run `cargo install --package ra_lsp_server` to install the server
+binary into `~/.cargo/bin`, and then will build and install plugin from
+`editors/code`. See
+[this](https://github.com/rust-analyzer/rust-analyzer/blob/69ee5c9c5ef212f7911028c9ddf581559e6565c3/crates/tools/src/main.rs#L37-L56)
+for details. The installation is expected to *just work*, if it doesn't, report
+bugs!
+
+It's better to remove existing Rust plugins to avoid interference.
+
+Beyond basic LSP features, there are some extension commands which you can
+invoke via <kbd>Ctrl+Shift+P</kbd> or bind to a shortcut. See [./features.md](./features.md)
+for details.
+
+### Settings
+
+* `rust-analyzer.highlightingOn`: enables experimental syntax highlighting
+* `rust-analyzer.showWorkspaceLoadedNotification`: to ease troubleshooting, a
+  notification is shown by default when a workspace is loaded
+* `rust-analyzer.enableEnhancedTyping`: by default, rust-analyzer intercepts
+  `Enter` key to make it easier to continue comments
+* `rust-analyzer.raLspServerPath`: path to `ra_lsp_server` executable
+* `rust-analyzer.enableCargoWatchOnStartup`: prompt to install & enable `cargo
+  watch` for live error highlighting (note, this **does not** use rust-analyzer)
+* `rust-analyzer.trace.server`: enables internal logging
+
+
+## Emacs
+
+Prerequisites:
+
+`emacs-lsp`, `dash` and `ht` packages.
+
+Installation:
+
+* add
+[ra-emacs-lsp.el](https://github.com/rust-analyzer/rust-analyzer/blob/69ee5c9c5ef212f7911028c9ddf581559e6565c3/editors/emacs/ra-emacs-lsp.el)
+to load path and require it in `init.el`
+* run `lsp` in a rust buffer
+* (Optionally) bind commands like `rust-analyzer-join-lines` or `rust-analyzer-extend-selection` to keys
diff --git a/docs/user/features.md b/docs/user/features.md
new file mode 100644
index 000000000..b9d2aa84f
--- /dev/null
+++ b/docs/user/features.md
@@ -0,0 +1,359 @@
+This documents is an index of features that 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
+project and dependencies. This **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
+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, excluding `stdlib`
+- `foo#*` searches for `foo` function among dependencies.
+
+That is, `#` switches from "types" to all symbols, `*` switches from the current
+workspace to dependencies.
+
+### Document Symbol <kbd>ctrl+shift+o</kbd>
+
+Provides a tree of the symbols defined in the file. Can be used to
+
+* fuzzy search symbol in a file (super useful)
+* draw breadcrumbs to describe the context around the cursor
+* draw outline of the file
+
+### On Typing Assists
+
+Some features trigger on typing certain characters:
+
+- 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
+
+### Commands <kbd>ctrl+shift+p</kbd>
+
+#### Extend Selection
+
+Extends the current selection to the encompassing syntactic construct
+(expression, statement, item, module, etc). It works with multiple cursors. Do
+bind this command to a key, it's super-useful! Expected to be upstreamed to LSP
+soonish: https://github.com/Microsoft/language-server-protocol/issues/613
+
+#### Run
+
+Shows 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!
+
+#### Parent Module
+
+Navigates to the parent module of the current module.
+
+#### Matching Brace
+
+If the cursor is on any brace (`<>(){}[]`) which is a part of a brace-pair,
+moves cursor to the matching brace. It uses the actual parser to determine
+braces, so it won't confuse generics with comparisons.
+
+#### Join Lines
+
+Join selected lines into one, smartly fixing up whitespace and trailing commas.
+
+#### Show Syntax Tree
+
+Shows the parse tree of the current file. It exists mostly for debugging
+rust-analyzer itself.
+
+#### Status
+
+Shows internal statistic about memory usage of rust-analyzer
+
+#### Run garbage collection
+
+Manually triggers GC
+
+### Code Actions (Assists)
+
+These are triggered in a particular context via light bulb. We use custom code on
+the VS Code side to be able to position cursor. `<|>` signifies cursor
+
+- Add `#[derive]`
+
+```rust
+// before:
+struct Foo {
+    <|>x: i32
+}
+// after:
+#[derive(<|>)]
+struct Foo {
+    x: i32
+}
+```
+
+- Add `impl`
+
+```rust
+// before:
+struct Foo<'a, T: Debug> {
+    <|>t: T
+}
+// after:
+struct Foo<'a, T: Debug> {
+    t: T
+}
+
+impl<'a, T: Debug> Foo<'a, T> {
+    <|>
+}
+```
+
+- Add missing `impl` members
+
+```rust
+// before:
+trait Foo {
+    fn foo(&self);
+    fn bar(&self);
+    fn baz(&self);
+}
+
+struct S;
+
+impl Foo for S {
+    fn bar(&self) {}
+    <|>
+}
+
+// after:
+trait Foo {
+    fn foo(&self);
+    fn bar(&self);
+    fn baz(&self);
+}
+
+struct S;
+
+impl Foo for S {
+    fn bar(&self) {}
+    fn foo(&self) { unimplemented!() }
+    fn baz(&self) { unimplemented!() }<|>
+}
+```
+
+- Import path
+
+```rust
+// before:
+impl std::fmt::Debug<|> for Foo {
+}
+
+// after:
+use std::fmt::Debug;
+
+impl Debug<|> for Foo {
+}
+```
+
+- Change Visibility
+
+```rust
+// before:
+<|>fn foo() {}
+
+// after:
+<|>pub(crate) fn foo() {}
+
+// after:
+<|>pub fn foo() {}
+```
+
+- Fill match arms
+
+```rust
+// before:
+enum A {
+    As,
+    Bs,
+    Cs(String),
+    Ds(String, String),
+    Es{x: usize, y: usize}
+}
+
+fn main() {
+    let a = A::As;
+    match a<|> {}
+}
+
+// after:
+enum A {
+    As,
+    Bs,
+    Cs(String),
+    Ds(String, String),
+    Es{x: usize, y: usize}
+}
+
+fn main() {
+    let a = A::As;
+    match <|>a {
+        A::As => (),
+        A::Bs => (),
+        A::Cs(_) => (),
+        A::Ds(_, _) => (),
+        A::Es{x, y} => (),
+    }
+}
+```
+
+-- Fill struct fields
+
+```rust
+// before:
+struct S<'a, D> {
+    a: u32,
+    b: String,
+    c: (i32, i32),
+    d: D,
+    r: &'a str,
+}
+
+fn main() {
+    let s = S<|> {}
+}
+
+// after:
+struct S<'a, D> {
+    a: u32,
+    b: String,
+    c: (i32, i32),
+    d: D,
+    r: &'a str,
+}
+
+fn main() {
+    let s = <|>S {
+        a: (),
+        b: (),
+        c: (),
+        d: (),
+        r: (),
+    }
+}
+```
+
+- Flip `,`
+
+```rust
+// before:
+fn foo(x: usize,<|> dim: (usize, usize)) {}
+// after:
+fn foo(dim: (usize, usize), x: usize) {}
+```
+
+- Introduce variable:
+
+```rust
+// before:
+fn foo() {
+    foo(<|>1 + 1<|>);
+}
+
+// after:
+fn foo() {
+    let var_name = 1 + 1;
+    foo(var_name);
+}
+```
+
+-- Remove `dbg!`
+
+```rust
+// before:
+fn foo(n: usize) {
+    if let Some(_) = dbg!(n.<|>checked_sub(4)) {
+        // ...
+    }
+}
+
+// after:
+fn foo(n: usize) {
+    if let Some(_) = n.<|>checked_sub(4) {
+        // ...
+    }
+}
+```
+
+- Replace if-let with match:
+
+```rust
+// before:
+impl VariantData {
+    pub fn is_struct(&self) -> bool {
+        if <|>let VariantData::Struct(..) = *self {
+            true
+        } else {
+            false
+        }
+    }
+}
+
+// after:
+impl VariantData {
+    pub fn is_struct(&self) -> bool {
+        <|>match *self {
+            VariantData::Struct(..) => true,
+            _ => false,
+        }
+    }
+}
+```
+
+- Split import
+
+```rust
+// before:
+use algo:<|>:visitor::{Visitor, visit};
+//after:
+use algo::{<|>visitor::{Visitor, visit}};
+```
+
+### Magic Completions
+
+In addition to usual reference completion, rust-analyzer provides some ✨magic✨
+completions as well:
+
+Keywords like `if`, `else` `while`, `loop` are completed with braces, and cursor
+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.
+
+There are postifx completions, which can be triggerd by typing something like
+`foo().if`. The word after `.` determines postifx completion, possible variants are:
+
+- `expr.if` -> `if expr {}`
+- `expr.match` -> `match expr {}`
+- `expr.while` -> `while expr {}`
+- `expr.ref` -> `&expr`
+- `expr.refm` -> `&mut expr`
+- `expr.not` -> `!expr`
+- `expr.dbg` -> `dbg!(expr)`
+
+There also snippet completions:
+
+#### Inside Expressions
+
+- `pd` -> `println!("{:?}")`
+- `ppd` -> `println!("{:#?}")`
+
+#### Inside Modules
+
+- `tfn` -> `#[test] fn f(){}`
+