aboutsummaryrefslogtreecommitdiff
path: root/docs
diff options
context:
space:
mode:
Diffstat (limited to 'docs')
-rw-r--r--docs/dev/lsp-extensions.md10
-rw-r--r--docs/dev/lsp-features.md72
-rw-r--r--docs/user/features.md218
-rw-r--r--docs/user/generated_assists.adoc (renamed from docs/user/assists.md)518
-rw-r--r--docs/user/generated_features.adoc298
-rw-r--r--docs/user/manual.adoc (renamed from docs/user/readme.adoc)51
6 files changed, 708 insertions, 459 deletions
diff --git a/docs/dev/lsp-extensions.md b/docs/dev/lsp-extensions.md
index d06da355d..b7237ee90 100644
--- a/docs/dev/lsp-extensions.md
+++ b/docs/dev/lsp-extensions.md
@@ -7,6 +7,16 @@ All capabilities are enabled via `experimental` field of `ClientCapabilities` or
7Requests which we hope to upstream live under `experimental/` namespace. 7Requests which we hope to upstream live under `experimental/` namespace.
8Requests, which are likely to always remain specific to `rust-analyzer` are under `rust-analyzer/` namespace. 8Requests, which are likely to always remain specific to `rust-analyzer` are under `rust-analyzer/` namespace.
9 9
10If you want to be notified about the changes to this document, subscribe to [#4604](https://github.com/rust-analyzer/rust-analyzer/issues/4604).
11
12## `initializationOptions`
13
14As `initializationOptions`, `rust-analyzer` expects `"rust-analyzer"` section of the configuration.
15That is, `rust-analyzer` usually sends `"workspace/configuration"` request with `{ "items": ["rust-analyzer"] }` payload.
16`initializationOptions` should contain the same data that would be in the first item of the result.
17It's OK to not send anything, then all the settings would take their default values.
18However, some settings can not be changed after startup at the moment.
19
10## Snippet `TextEdit` 20## Snippet `TextEdit`
11 21
12**Issue:** https://github.com/microsoft/language-server-protocol/issues/724 22**Issue:** https://github.com/microsoft/language-server-protocol/issues/724
diff --git a/docs/dev/lsp-features.md b/docs/dev/lsp-features.md
deleted file mode 100644
index 00b0867d7..000000000
--- a/docs/dev/lsp-features.md
+++ /dev/null
@@ -1,72 +0,0 @@
1# Supported LSP features
2
3This list documents LSP features, supported by rust-analyzer.
4
5## General
6- [x] [initialize](https://microsoft.github.io/language-server-protocol/specification#initialize)
7- [x] [initialized](https://microsoft.github.io/language-server-protocol/specification#initialized)
8- [x] [shutdown](https://microsoft.github.io/language-server-protocol/specification#shutdown)
9- [ ] [exit](https://microsoft.github.io/language-server-protocol/specification#exit)
10- [x] [$/cancelRequest](https://microsoft.github.io/language-server-protocol/specification#cancelRequest)
11
12## Workspace
13- [ ] [workspace/workspaceFolders](https://microsoft.github.io/language-server-protocol/specification#workspace_workspaceFolders)
14- [ ] [workspace/didChangeWorkspaceFolders](https://microsoft.github.io/language-server-protocol/specification#workspace_didChangeWorkspaceFolders)
15- [x] [workspace/didChangeConfiguration](https://microsoft.github.io/language-server-protocol/specification#workspace_didChangeConfiguration)
16- [ ] [workspace/configuration](https://microsoft.github.io/language-server-protocol/specification#workspace_configuration)
17- [x] [workspace/didChangeWatchedFiles](https://microsoft.github.io/language-server-protocol/specification#workspace_didChangeWatchedFiles)
18- [x] [workspace/symbol](https://microsoft.github.io/language-server-protocol/specification#workspace_symbol)
19- [ ] [workspace/applyEdit](https://microsoft.github.io/language-server-protocol/specification#workspace_applyEdit)
20
21## Text Synchronization
22- [x] [textDocument/didOpen](https://microsoft.github.io/language-server-protocol/specification#textDocument_didOpen)
23- [x] [textDocument/didChange](https://microsoft.github.io/language-server-protocol/specification#textDocument_didChange)
24- [ ] [textDocument/willSave](https://microsoft.github.io/language-server-protocol/specification#textDocument_willSave)
25- [ ] [textDocument/willSaveWaitUntil](https://microsoft.github.io/language-server-protocol/specification#textDocument_willSaveWaitUntil)
26- [x] [textDocument/didSave](https://microsoft.github.io/language-server-protocol/specification#textDocument_didSave)
27- [x] [textDocument/didClose](https://microsoft.github.io/language-server-protocol/specification#textDocument_didClose)
28
29## Diagnostics
30- [x] [textDocument/publishDiagnostics](https://microsoft.github.io/language-server-protocol/specification#textDocument_publishDiagnostics)
31
32## Lanuguage Features
33- [x] [textDocument/completion](https://microsoft.github.io/language-server-protocol/specification#textDocument_completion)
34 - open close: false
35 - change: Full
36 - will save: false
37 - will save wait until: false
38 - save: false
39- [x] [completionItem/resolve](https://microsoft.github.io/language-server-protocol/specification#completionItem_resolve)
40 - resolve provider: none
41 - trigger characters: `:`, `.`
42- [x] [textDocument/hover](https://microsoft.github.io/language-server-protocol/specification#textDocument_hover)
43- [x] [textDocument/signatureHelp](https://microsoft.github.io/language-server-protocol/specification#textDocument_signatureHelp)
44 - trigger characters: `(`, `,`
45- [ ] [textDocument/declaration](https://microsoft.github.io/language-server-protocol/specification#textDocument_declaration)
46- [x] [textDocument/definition](https://microsoft.github.io/language-server-protocol/specification#textDocument_definition)
47- [x] [textDocument/typeDefinition](https://microsoft.github.io/language-server-protocol/specification#textDocument_typeDefinition)
48- [x] [textDocument/implementation](https://microsoft.github.io/language-server-protocol/specification#textDocument_implementation)
49- [x] [textDocument/references](https://microsoft.github.io/language-server-protocol/specification#textDocument_references)
50- [x] [textDocument/documentHighlight](https://microsoft.github.io/language-server-protocol/specification#textDocument_documentHighlight)
51- [x] [textDocument/documentSymbol](https://microsoft.github.io/language-server-protocol/specification#textDocument_documentSymbol)
52- [x] [textDocument/codeAction](https://microsoft.github.io/language-server-protocol/specification#textDocument_codeAction)
53- [x] [textDocument/selectionRange](https://github.com/Microsoft/language-server-protocol/issues/613)
54 - rust-analyzer.syntaxTree
55 - rust-analyzer.matchingBrace
56 - rust-analyzer.parentModule
57 - rust-analyzer.joinLines
58 - rust-analyzer.run
59 - rust-analyzer.analyzerStatus
60- [x] [textDocument/codeLens](https://microsoft.github.io/language-server-protocol/specification#textDocument_codeLens)
61- [x] [codeLens/resolve](https://microsoft.github.io/language-server-protocol/specification#codeLens_resolve)
62- [ ] [documentLink/resolve](https://microsoft.github.io/language-server-protocol/specification#documentLink_resolve)
63- [ ] [textDocument/documentColor](https://microsoft.github.io/language-server-protocol/specification#textDocument_documentColor)
64- [ ] [textDocument/colorPresentation](https://microsoft.github.io/language-server-protocol/specification#textDocument_colorPresentation)
65- [x] [textDocument/formatting](https://microsoft.github.io/language-server-protocol/specification#textDocument_formatting)
66- [ ] [textDocument/rangeFormatting](https://microsoft.github.io/language-server-protocol/specification#textDocument_rangeFormatting)
67- [x] [textDocument/onTypeFormatting](https://microsoft.github.io/language-server-protocol/specification#textDocument_onTypeFormatting)
68 - first trigger character: `=`
69 - more trigger character `.`
70- [x] [textDocument/rename](https://microsoft.github.io/language-server-protocol/specification#textDocument_rename)
71- [x] [textDocument/prepareRename](https://microsoft.github.io/language-server-protocol/specification#textDocument_prepareRename)
72- [x] [textDocument/foldingRange](https://microsoft.github.io/language-server-protocol/specification#textDocument_foldingRange)
diff --git a/docs/user/features.md b/docs/user/features.md
deleted file mode 100644
index 12ecdec13..000000000
--- a/docs/user/features.md
+++ /dev/null
@@ -1,218 +0,0 @@
1This document is an index of features that the rust-analyzer language server
2provides. Shortcuts are for the default VS Code layout. If there's no shortcut,
3you can use <kbd>Ctrl+Shift+P</kbd> to search for the corresponding action.
4
5### Workspace Symbol <kbd>ctrl+t</kbd>
6
7Uses fuzzy-search to find types, modules and functions by name across your
8project and dependencies. This is **the** most useful feature, which improves code
9navigation tremendously. It mostly works on top of the built-in LSP
10functionality, however `#` and `*` symbols can be used to narrow down the
11search. Specifically,
12
13- `Foo` searches for `Foo` type in the current workspace
14- `foo#` searches for `foo` function in the current workspace
15- `Foo*` searches for `Foo` type among dependencies, including `stdlib`
16- `foo#*` searches for `foo` function among dependencies
17
18That is, `#` switches from "types" to all symbols, `*` switches from the current
19workspace to dependencies.
20
21### Document Symbol <kbd>ctrl+shift+o</kbd>
22
23Provides a tree of the symbols defined in the file. Can be used to
24
25* fuzzy search symbol in a file (super useful)
26* draw breadcrumbs to describe the context around the cursor
27* draw outline of the file
28
29### On Typing Assists
30
31Some features trigger on typing certain characters:
32
33- typing `let =` tries to smartly add `;` if `=` is followed by an existing expression
34- Enter inside comments automatically inserts `///`
35- typing `.` in a chain method call auto-indents
36
37### Extend Selection
38
39Extends the current selection to the encompassing syntactic construct
40(expression, statement, item, module, etc). It works with multiple cursors. This
41is a relatively new feature of LSP:
42https://github.com/Microsoft/language-server-protocol/issues/613, check your
43editor's LSP library to see if this feature is supported.
44
45### Go to Definition
46
47Navigates to the definition of an identifier.
48
49### Go to Implementation
50
51Navigates to the impl block of structs, enums or traits. Also implemented as a code lens.
52
53### Go to Type Defintion
54
55Navigates to the type of an identifier.
56
57### Commands <kbd>ctrl+shift+p</kbd>
58
59#### Run
60
61Shows a popup suggesting to run a test/benchmark/binary **at the current cursor
62location**. Super useful for repeatedly running just a single test. Do bind this
63to a shortcut!
64
65#### Parent Module
66
67Navigates to the parent module of the current module.
68
69#### Matching Brace
70
71If the cursor is on any brace (`<>(){}[]`) which is a part of a brace-pair,
72moves cursor to the matching brace. It uses the actual parser to determine
73braces, so it won't confuse generics with comparisons.
74
75#### Join Lines
76
77Join selected lines into one, smartly fixing up whitespace and trailing commas.
78
79#### Show Syntax Tree
80
81Shows the parse tree of the current file. It exists mostly for debugging
82rust-analyzer itself.
83
84#### Expand Macro Recursively
85
86Shows the full macro expansion of the macro at current cursor.
87
88#### Status
89
90Shows internal statistic about memory usage of rust-analyzer.
91
92#### Show RA Version
93
94Show current rust-analyzer version.
95
96#### Toggle inlay hints
97
98Toggle inlay hints view for the current workspace.
99It is recommended to assign a shortcut for this command to quickly turn off
100inlay hints when they prevent you from reading/writing the code.
101
102#### Run Garbage Collection
103
104Manually triggers GC.
105
106#### Start Cargo Watch
107
108Start `cargo watch` for live error highlighting. Will prompt to install if it's not already installed.
109
110#### Stop Cargo Watch
111
112Stop `cargo watch`.
113
114#### Structural Seach and Replace
115
116Search and replace with named wildcards that will match any expression.
117The syntax for a structural search replace command is `<search_pattern> ==>> <replace_pattern>`. A `$<name>:expr` placeholder in the search pattern will match any expression and `$<name>` will reference it in the replacement. Available via the command `rust-analyzer.ssr`.
118
119```rust
120// Using structural search replace command [foo($a:expr, $b:expr) ==>> ($a).foo($b)]
121
122// BEFORE
123String::from(foo(y + 5, z))
124
125// AFTER
126String::from((y + 5).foo(z))
127```
128
129### Assists (Code Actions)
130
131Assists, or code actions, are small local refactorings, available in a particular context.
132They are usually triggered by a shortcut or by clicking a light bulb icon in the editor.
133
134See [assists.md](./assists.md) for the list of available assists.
135
136### Magic Completions
137
138In addition to usual reference completion, rust-analyzer provides some ✨magic✨
139completions as well:
140
141Keywords like `if`, `else` `while`, `loop` are completed with braces, and cursor
142is placed at the appropriate position. Even though `if` is easy to type, you
143still want to complete it, to get ` { }` for free! `return` is inserted with a
144space or `;` depending on the return type of the function.
145
146When completing a function call, `()` are automatically inserted. If a function
147takes arguments, the cursor is positioned inside the parenthesis.
148
149There are postfix completions, which can be triggered by typing something like
150`foo().if`. The word after `.` determines postfix completion. Possible variants are:
151
152- `expr.if` -> `if expr {}` or `if let ... {}` for `Option` or `Result`
153- `expr.match` -> `match expr {}`
154- `expr.while` -> `while expr {}` or `while let ... {}` for `Option` or `Result`
155- `expr.ref` -> `&expr`
156- `expr.refm` -> `&mut expr`
157- `expr.not` -> `!expr`
158- `expr.dbg` -> `dbg!(expr)`
159
160There also snippet completions:
161
162#### Inside Expressions
163
164- `pd` -> `println!("{:?}")`
165- `ppd` -> `println!("{:#?}")`
166
167#### Inside Modules
168
169- `tfn` -> `#[test] fn f(){}`
170- `tmod` ->
171```rust
172#[cfg(test)]
173mod tests {
174 use super::*;
175
176 #[test]
177 fn test_fn() {}
178}
179```
180
181### Code Highlighting
182
183Experimental feature to let rust-analyzer highlight Rust code instead of using the
184default highlighter.
185
186#### Rainbow Highlighting
187
188Experimental feature that, given code highlighting using rust-analyzer is
189active, will pick unique colors for identifiers.
190
191### Code hints
192
193Rust-analyzer has two types of hints to show the information about the code:
194
195* hover hints, appearing on hover on any element.
196
197These contain extended information on the hovered language item.
198
199* inlay hints, shown near the element hinted directly in the editor.
200
201Two types of inlay hints are displayed currently:
202
203* type hints, displaying the minimal information on the type of the expression (if the information is available)
204* method chaining hints, type information for multi-line method chains
205* parameter name hints, displaying the names of the parameters in the corresponding methods
206
207#### VS Code
208
209In VS Code, the following settings can be used to configure the inlay hints:
210
211* `rust-analyzer.inlayHints.typeHints` - enable hints for inferred types.
212* `rust-analyzer.inlayHints.chainingHints` - enable hints for inferred types on method chains.
213* `rust-analyzer.inlayHints.parameterHints` - enable hints for function parameters.
214* `rust-analyzer.inlayHints.maxLength` — shortens the hints if their length exceeds the value specified. If no value is specified (`null`), no shortening is applied.
215
216**Note:** VS Code does not have native support for inlay hints [yet](https://github.com/microsoft/vscode/issues/16221) and the hints are implemented using decorations.
217This approach has limitations, the caret movement and bracket highlighting near the edges of the hint may be weird:
218[1](https://github.com/rust-analyzer/rust-analyzer/issues/1623), [2](https://github.com/rust-analyzer/rust-analyzer/issues/3453).
diff --git a/docs/user/assists.md b/docs/user/generated_assists.adoc
index a1058ecde..4d2fb31d4 100644
--- a/docs/user/assists.md
+++ b/docs/user/generated_assists.adoc
@@ -1,18 +1,17 @@
1# Assists 1[discrete]
2 2=== `add_custom_impl`
3Cursor position or selection is signified by `┃` character. 3**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_assists/src/handlers/add_custom_impl.rs#L14[add_custom_impl.rs]
4
5
6## `add_custom_impl`
7 4
8Adds impl block for derived trait. 5Adds impl block for derived trait.
9 6
7.Before
10```rust 8```rust
11// BEFORE
12#[derive(Deb┃ug, Display)] 9#[derive(Deb┃ug, Display)]
13struct S; 10struct S;
11```
14 12
15// AFTER 13.After
14```rust
16#[derive(Display)] 15#[derive(Display)]
17struct S; 16struct S;
18 17
@@ -21,18 +20,23 @@ impl Debug for S {
21} 20}
22``` 21```
23 22
24## `add_derive` 23
24[discrete]
25=== `add_derive`
26**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_assists/src/handlers/add_derive.rs#L9[add_derive.rs]
25 27
26Adds a new `#[derive()]` clause to a struct or enum. 28Adds a new `#[derive()]` clause to a struct or enum.
27 29
30.Before
28```rust 31```rust
29// BEFORE
30struct Point { 32struct Point {
31 x: u32, 33 x: u32,
32 y: u32,┃ 34 y: u32,┃
33} 35}
36```
34 37
35// AFTER 38.After
39```rust
36#[derive($0)] 40#[derive($0)]
37struct Point { 41struct Point {
38 x: u32, 42 x: u32,
@@ -40,36 +44,69 @@ struct Point {
40} 44}
41``` 45```
42 46
43## `add_explicit_type` 47
48[discrete]
49=== `add_explicit_type`
50**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_assists/src/handlers/add_explicit_type.rs#L9[add_explicit_type.rs]
44 51
45Specify type for a let binding. 52Specify type for a let binding.
46 53
54.Before
47```rust 55```rust
48// BEFORE
49fn main() { 56fn main() {
50 let x┃ = 92; 57 let x┃ = 92;
51} 58}
59```
52 60
53// AFTER 61.After
62```rust
54fn main() { 63fn main() {
55 let x: i32 = 92; 64 let x: i32 = 92;
56} 65}
57``` 66```
58 67
59## `add_function` 68
69[discrete]
70=== `add_from_impl_for_enum`
71**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_assists/src/handlers/add_from_impl_for_enum.rs#L7[add_from_impl_for_enum.rs]
72
73Adds a From impl for an enum variant with one tuple field.
74
75.Before
76```rust
77enum A { ┃One(u32) }
78```
79
80.After
81```rust
82enum A { One(u32) }
83
84impl From<u32> for A {
85 fn from(v: u32) -> Self {
86 A::One(v)
87 }
88}
89```
90
91
92[discrete]
93=== `add_function`
94**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_assists/src/handlers/add_function.rs#L19[add_function.rs]
60 95
61Adds a stub function with a signature matching the function under the cursor. 96Adds a stub function with a signature matching the function under the cursor.
62 97
98.Before
63```rust 99```rust
64// BEFORE
65struct Baz; 100struct Baz;
66fn baz() -> Baz { Baz } 101fn baz() -> Baz { Baz }
67fn foo() { 102fn foo() {
68 bar┃("", baz()); 103 bar┃("", baz());
69} 104}
70 105
106```
71 107
72// AFTER 108.After
109```rust
73struct Baz; 110struct Baz;
74fn baz() -> Baz { Baz } 111fn baz() -> Baz { Baz }
75fn foo() { 112fn foo() {
@@ -82,33 +119,43 @@ fn bar(arg: &str, baz: Baz) {
82 119
83``` 120```
84 121
85## `add_hash` 122
123[discrete]
124=== `add_hash`
125**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_assists/src/handlers/raw_string.rs#L65[raw_string.rs]
86 126
87Adds a hash to a raw string literal. 127Adds a hash to a raw string literal.
88 128
129.Before
89```rust 130```rust
90// BEFORE
91fn main() { 131fn main() {
92 r#"Hello,┃ World!"#; 132 r#"Hello,┃ World!"#;
93} 133}
134```
94 135
95// AFTER 136.After
137```rust
96fn main() { 138fn main() {
97 r##"Hello, World!"##; 139 r##"Hello, World!"##;
98} 140}
99``` 141```
100 142
101## `add_impl` 143
144[discrete]
145=== `add_impl`
146**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_assists/src/handlers/add_impl.rs#L6[add_impl.rs]
102 147
103Adds a new inherent impl for a type. 148Adds a new inherent impl for a type.
104 149
150.Before
105```rust 151```rust
106// BEFORE
107struct Ctx<T: Clone> { 152struct Ctx<T: Clone> {
108 data: T,┃ 153 data: T,┃
109} 154}
155```
110 156
111// AFTER 157.After
158```rust
112struct Ctx<T: Clone> { 159struct Ctx<T: Clone> {
113 data: T, 160 data: T,
114} 161}
@@ -118,12 +165,15 @@ impl<T: Clone> Ctx<T> {
118} 165}
119``` 166```
120 167
121## `add_impl_default_members` 168
169[discrete]
170=== `add_impl_default_members`
171**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_assists/src/handlers/add_missing_impl_members.rs#L64[add_missing_impl_members.rs]
122 172
123Adds scaffold for overriding default impl members. 173Adds scaffold for overriding default impl members.
124 174
175.Before
125```rust 176```rust
126// BEFORE
127trait Trait { 177trait Trait {
128 Type X; 178 Type X;
129 fn foo(&self); 179 fn foo(&self);
@@ -135,8 +185,10 @@ impl Trait for () {
135 fn foo(&self) {}┃ 185 fn foo(&self) {}┃
136 186
137} 187}
188```
138 189
139// AFTER 190.After
191```rust
140trait Trait { 192trait Trait {
141 Type X; 193 Type X;
142 fn foo(&self); 194 fn foo(&self);
@@ -151,12 +203,15 @@ impl Trait for () {
151} 203}
152``` 204```
153 205
154## `add_impl_missing_members` 206
207[discrete]
208=== `add_impl_missing_members`
209**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_assists/src/handlers/add_missing_impl_members.rs#L24[add_missing_impl_members.rs]
155 210
156Adds scaffold for required impl members. 211Adds scaffold for required impl members.
157 212
213.Before
158```rust 214```rust
159// BEFORE
160trait Trait<T> { 215trait Trait<T> {
161 Type X; 216 Type X;
162 fn foo(&self) -> T; 217 fn foo(&self) -> T;
@@ -166,8 +221,10 @@ trait Trait<T> {
166impl Trait<u32> for () {┃ 221impl Trait<u32> for () {┃
167 222
168} 223}
224```
169 225
170// AFTER 226.After
227```rust
171trait Trait<T> { 228trait Trait<T> {
172 Type X; 229 Type X;
173 fn foo(&self) -> T; 230 fn foo(&self) -> T;
@@ -182,17 +239,22 @@ impl Trait<u32> for () {
182} 239}
183``` 240```
184 241
185## `add_new` 242
243[discrete]
244=== `add_new`
245**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_assists/src/handlers/add_new.rs#L12[add_new.rs]
186 246
187Adds a new inherent impl for a type. 247Adds a new inherent impl for a type.
188 248
249.Before
189```rust 250```rust
190// BEFORE
191struct Ctx<T: Clone> { 251struct Ctx<T: Clone> {
192 data: T,┃ 252 data: T,┃
193} 253}
254```
194 255
195// AFTER 256.After
257```rust
196struct Ctx<T: Clone> { 258struct Ctx<T: Clone> {
197 data: T, 259 data: T,
198} 260}
@@ -203,25 +265,33 @@ impl<T: Clone> Ctx<T> {
203 265
204``` 266```
205 267
206## `add_turbo_fish` 268
269[discrete]
270=== `add_turbo_fish`
271**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_assists/src/handlers/add_turbo_fish.rs#L10[add_turbo_fish.rs]
207 272
208Adds `::<_>` to a call of a generic method or function. 273Adds `::<_>` to a call of a generic method or function.
209 274
275.Before
210```rust 276```rust
211// BEFORE
212fn make<T>() -> T { todo!() } 277fn make<T>() -> T { todo!() }
213fn main() { 278fn main() {
214 let x = make┃(); 279 let x = make┃();
215} 280}
281```
216 282
217// AFTER 283.After
284```rust
218fn make<T>() -> T { todo!() } 285fn make<T>() -> T { todo!() }
219fn main() { 286fn main() {
220 let x = make::<${0:_}>(); 287 let x = make::<${0:_}>();
221} 288}
222``` 289```
223 290
224## `apply_demorgan` 291
292[discrete]
293=== `apply_demorgan`
294**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_assists/src/handlers/apply_demorgan.rs#L5[apply_demorgan.rs]
225 295
226Apply [De Morgan's law](https://en.wikipedia.org/wiki/De_Morgan%27s_laws). 296Apply [De Morgan's law](https://en.wikipedia.org/wiki/De_Morgan%27s_laws).
227This transforms expressions of the form `!l || !r` into `!(l && r)`. 297This transforms expressions of the form `!l || !r` into `!(l && r)`.
@@ -229,29 +299,36 @@ This also works with `&&`. This assist can only be applied with the cursor
229on either `||` or `&&`, with both operands being a negation of some kind. 299on either `||` or `&&`, with both operands being a negation of some kind.
230This means something of the form `!x` or `x != y`. 300This means something of the form `!x` or `x != y`.
231 301
302.Before
232```rust 303```rust
233// BEFORE
234fn main() { 304fn main() {
235 if x != 4 ||┃ !y {} 305 if x != 4 ||┃ !y {}
236} 306}
307```
237 308
238// AFTER 309.After
310```rust
239fn main() { 311fn main() {
240 if !(x == 4 && y) {} 312 if !(x == 4 && y) {}
241} 313}
242``` 314```
243 315
244## `auto_import` 316
317[discrete]
318=== `auto_import`
319**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_assists/src/handlers/auto_import.rs#L18[auto_import.rs]
245 320
246If the name is unresolved, provides all possible imports for it. 321If the name is unresolved, provides all possible imports for it.
247 322
323.Before
248```rust 324```rust
249// BEFORE
250fn main() { 325fn main() {
251 let map = HashMap┃::new(); 326 let map = HashMap┃::new();
252} 327}
328```
253 329
254// AFTER 330.After
331```rust
255use std::collections::HashMap; 332use std::collections::HashMap;
256 333
257fn main() { 334fn main() {
@@ -259,68 +336,59 @@ fn main() {
259} 336}
260``` 337```
261 338
262## `change_lifetime_anon_to_named`
263
264Change an anonymous lifetime to a named lifetime.
265
266```rust
267// BEFORE
268impl Cursor<'_┃> {
269 fn node(self) -> &SyntaxNode {
270 match self {
271 Cursor::Replace(node) | Cursor::Before(node) => node,
272 }
273 }
274}
275
276// AFTER
277impl<'a> Cursor<'a> {
278 fn node(self) -> &SyntaxNode {
279 match self {
280 Cursor::Replace(node) | Cursor::Before(node) => node,
281 }
282 }
283}
284```
285 339
286## `change_return_type_to_result` 340[discrete]
341=== `change_return_type_to_result`
342**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_assists/src/handlers/change_return_type_to_result.rs#L8[change_return_type_to_result.rs]
287 343
288Change the function's return type to Result. 344Change the function's return type to Result.
289 345
346.Before
290```rust 347```rust
291// BEFORE
292fn foo() -> i32┃ { 42i32 } 348fn foo() -> i32┃ { 42i32 }
349```
293 350
294// AFTER 351.After
352```rust
295fn foo() -> Result<i32, ${0:_}> { Ok(42i32) } 353fn foo() -> Result<i32, ${0:_}> { Ok(42i32) }
296``` 354```
297 355
298## `change_visibility` 356
357[discrete]
358=== `change_visibility`
359**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_assists/src/handlers/change_visibility.rs#L14[change_visibility.rs]
299 360
300Adds or changes existing visibility specifier. 361Adds or changes existing visibility specifier.
301 362
363.Before
302```rust 364```rust
303// BEFORE
304┃fn frobnicate() {} 365┃fn frobnicate() {}
366```
305 367
306// AFTER 368.After
369```rust
307pub(crate) fn frobnicate() {} 370pub(crate) fn frobnicate() {}
308``` 371```
309 372
310## `convert_to_guarded_return` 373
374[discrete]
375=== `convert_to_guarded_return`
376**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_assists/src/handlers/early_return.rs#L21[early_return.rs]
311 377
312Replace a large conditional with a guarded return. 378Replace a large conditional with a guarded return.
313 379
380.Before
314```rust 381```rust
315// BEFORE
316fn main() { 382fn main() {
317 ┃if cond { 383 ┃if cond {
318 foo(); 384 foo();
319 bar(); 385 bar();
320 } 386 }
321} 387}
388```
322 389
323// AFTER 390.After
391```rust
324fn main() { 392fn main() {
325 if !cond { 393 if !cond {
326 return; 394 return;
@@ -330,12 +398,15 @@ fn main() {
330} 398}
331``` 399```
332 400
333## `fill_match_arms` 401
402[discrete]
403=== `fill_match_arms`
404**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_assists/src/handlers/fill_match_arms.rs#L14[fill_match_arms.rs]
334 405
335Adds missing clauses to a `match` expression. 406Adds missing clauses to a `match` expression.
336 407
408.Before
337```rust 409```rust
338// BEFORE
339enum Action { Move { distance: u32 }, Stop } 410enum Action { Move { distance: u32 }, Stop }
340 411
341fn handle(action: Action) { 412fn handle(action: Action) {
@@ -343,8 +414,10 @@ fn handle(action: Action) {
343 ┃ 414 ┃
344 } 415 }
345} 416}
417```
346 418
347// AFTER 419.After
420```rust
348enum Action { Move { distance: u32 }, Stop } 421enum Action { Move { distance: u32 }, Stop }
349 422
350fn handle(action: Action) { 423fn handle(action: Action) {
@@ -355,20 +428,25 @@ fn handle(action: Action) {
355} 428}
356``` 429```
357 430
358## `fix_visibility` 431
432[discrete]
433=== `fix_visibility`
434**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_assists/src/handlers/fix_visibility.rs#L13[fix_visibility.rs]
359 435
360Makes inaccessible item public. 436Makes inaccessible item public.
361 437
438.Before
362```rust 439```rust
363// BEFORE
364mod m { 440mod m {
365 fn frobnicate() {} 441 fn frobnicate() {}
366} 442}
367fn main() { 443fn main() {
368 m::frobnicate┃() {} 444 m::frobnicate┃() {}
369} 445}
446```
370 447
371// AFTER 448.After
449```rust
372mod m { 450mod m {
373 $0pub(crate) fn frobnicate() {} 451 $0pub(crate) fn frobnicate() {}
374} 452}
@@ -377,154 +455,231 @@ fn main() {
377} 455}
378``` 456```
379 457
380## `flip_binexpr` 458
459[discrete]
460=== `flip_binexpr`
461**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_assists/src/handlers/flip_binexpr.rs#L5[flip_binexpr.rs]
381 462
382Flips operands of a binary expression. 463Flips operands of a binary expression.
383 464
465.Before
384```rust 466```rust
385// BEFORE
386fn main() { 467fn main() {
387 let _ = 90 +┃ 2; 468 let _ = 90 +┃ 2;
388} 469}
470```
389 471
390// AFTER 472.After
473```rust
391fn main() { 474fn main() {
392 let _ = 2 + 90; 475 let _ = 2 + 90;
393} 476}
394``` 477```
395 478
396## `flip_comma` 479
480[discrete]
481=== `flip_comma`
482**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_assists/src/handlers/flip_comma.rs#L5[flip_comma.rs]
397 483
398Flips two comma-separated items. 484Flips two comma-separated items.
399 485
486.Before
400```rust 487```rust
401// BEFORE
402fn main() { 488fn main() {
403 ((1, 2),┃ (3, 4)); 489 ((1, 2),┃ (3, 4));
404} 490}
491```
405 492
406// AFTER 493.After
494```rust
407fn main() { 495fn main() {
408 ((3, 4), (1, 2)); 496 ((3, 4), (1, 2));
409} 497}
410``` 498```
411 499
412## `flip_trait_bound` 500
501[discrete]
502=== `flip_trait_bound`
503**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_assists/src/handlers/flip_trait_bound.rs#L9[flip_trait_bound.rs]
413 504
414Flips two trait bounds. 505Flips two trait bounds.
415 506
507.Before
416```rust 508```rust
417// BEFORE
418fn foo<T: Clone +┃ Copy>() { } 509fn foo<T: Clone +┃ Copy>() { }
510```
419 511
420// AFTER 512.After
513```rust
421fn foo<T: Copy + Clone>() { } 514fn foo<T: Copy + Clone>() { }
422``` 515```
423 516
424## `inline_local_variable` 517
518[discrete]
519=== `inline_local_variable`
520**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_assists/src/handlers/inline_local_variable.rs#L13[inline_local_variable.rs]
425 521
426Inlines local variable. 522Inlines local variable.
427 523
524.Before
428```rust 525```rust
429// BEFORE
430fn main() { 526fn main() {
431 let x┃ = 1 + 2; 527 let x┃ = 1 + 2;
432 x * 4; 528 x * 4;
433} 529}
530```
434 531
435// AFTER 532.After
533```rust
436fn main() { 534fn main() {
437 (1 + 2) * 4; 535 (1 + 2) * 4;
438} 536}
439``` 537```
440 538
441## `introduce_variable` 539
540[discrete]
541=== `introduce_named_lifetime`
542**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_assists/src/handlers/introduce_named_lifetime.rs#L12[introduce_named_lifetime.rs]
543
544Change an anonymous lifetime to a named lifetime.
545
546.Before
547```rust
548impl Cursor<'_┃> {
549 fn node(self) -> &SyntaxNode {
550 match self {
551 Cursor::Replace(node) | Cursor::Before(node) => node,
552 }
553 }
554}
555```
556
557.After
558```rust
559impl<'a> Cursor<'a> {
560 fn node(self) -> &SyntaxNode {
561 match self {
562 Cursor::Replace(node) | Cursor::Before(node) => node,
563 }
564 }
565}
566```
567
568
569[discrete]
570=== `introduce_variable`
571**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_assists/src/handlers/introduce_variable.rs#L14[introduce_variable.rs]
442 572
443Extracts subexpression into a variable. 573Extracts subexpression into a variable.
444 574
575.Before
445```rust 576```rust
446// BEFORE
447fn main() { 577fn main() {
448 ┃(1 + 2)┃ * 4; 578 ┃(1 + 2)┃ * 4;
449} 579}
580```
450 581
451// AFTER 582.After
583```rust
452fn main() { 584fn main() {
453 let $0var_name = (1 + 2); 585 let $0var_name = (1 + 2);
454 var_name * 4; 586 var_name * 4;
455} 587}
456``` 588```
457 589
458## `invert_if` 590
591[discrete]
592=== `invert_if`
593**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_assists/src/handlers/invert_if.rs#L12[invert_if.rs]
459 594
460Apply invert_if 595Apply invert_if
461This transforms if expressions of the form `if !x {A} else {B}` into `if x {B} else {A}` 596This transforms if expressions of the form `if !x {A} else {B}` into `if x {B} else {A}`
462This also works with `!=`. This assist can only be applied with the cursor 597This also works with `!=`. This assist can only be applied with the cursor
463on `if`. 598on `if`.
464 599
600.Before
465```rust 601```rust
466// BEFORE
467fn main() { 602fn main() {
468 if┃ !y { A } else { B } 603 if┃ !y { A } else { B }
469} 604}
605```
470 606
471// AFTER 607.After
608```rust
472fn main() { 609fn main() {
473 if y { B } else { A } 610 if y { B } else { A }
474} 611}
475``` 612```
476 613
477## `make_raw_string` 614
615[discrete]
616=== `make_raw_string`
617**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_assists/src/handlers/raw_string.rs#L10[raw_string.rs]
478 618
479Adds `r#` to a plain string literal. 619Adds `r#` to a plain string literal.
480 620
621.Before
481```rust 622```rust
482// BEFORE
483fn main() { 623fn main() {
484 "Hello,┃ World!"; 624 "Hello,┃ World!";
485} 625}
626```
486 627
487// AFTER 628.After
629```rust
488fn main() { 630fn main() {
489 r#"Hello, World!"#; 631 r#"Hello, World!"#;
490} 632}
491``` 633```
492 634
493## `make_usual_string` 635
636[discrete]
637=== `make_usual_string`
638**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_assists/src/handlers/raw_string.rs#L39[raw_string.rs]
494 639
495Turns a raw string into a plain string. 640Turns a raw string into a plain string.
496 641
642.Before
497```rust 643```rust
498// BEFORE
499fn main() { 644fn main() {
500 r#"Hello,┃ "World!""#; 645 r#"Hello,┃ "World!""#;
501} 646}
647```
502 648
503// AFTER 649.After
650```rust
504fn main() { 651fn main() {
505 "Hello, \"World!\""; 652 "Hello, \"World!\"";
506} 653}
507``` 654```
508 655
509## `merge_imports` 656
657[discrete]
658=== `merge_imports`
659**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_assists/src/handlers/merge_imports.rs#L14[merge_imports.rs]
510 660
511Merges two imports with a common prefix. 661Merges two imports with a common prefix.
512 662
663.Before
513```rust 664```rust
514// BEFORE
515use std::┃fmt::Formatter; 665use std::┃fmt::Formatter;
516use std::io; 666use std::io;
667```
517 668
518// AFTER 669.After
670```rust
519use std::{fmt::Formatter, io}; 671use std::{fmt::Formatter, io};
520``` 672```
521 673
522## `merge_match_arms` 674
675[discrete]
676=== `merge_match_arms`
677**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_assists/src/handlers/merge_match_arms.rs#L11[merge_match_arms.rs]
523 678
524Merges identical match arms. 679Merges identical match arms.
525 680
681.Before
526```rust 682```rust
527// BEFORE
528enum Action { Move { distance: u32 }, Stop } 683enum Action { Move { distance: u32 }, Stop }
529 684
530fn handle(action: Action) { 685fn handle(action: Action) {
@@ -533,8 +688,10 @@ fn handle(action: Action) {
533 Action::Stop => foo(), 688 Action::Stop => foo(),
534 } 689 }
535} 690}
691```
536 692
537// AFTER 693.After
694```rust
538enum Action { Move { distance: u32 }, Stop } 695enum Action { Move { distance: u32 }, Stop }
539 696
540fn handle(action: Action) { 697fn handle(action: Action) {
@@ -544,12 +701,15 @@ fn handle(action: Action) {
544} 701}
545``` 702```
546 703
547## `move_arm_cond_to_match_guard` 704
705[discrete]
706=== `move_arm_cond_to_match_guard`
707**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_assists/src/handlers/move_guard.rs#L56[move_guard.rs]
548 708
549Moves if expression from match arm body into a guard. 709Moves if expression from match arm body into a guard.
550 710
711.Before
551```rust 712```rust
552// BEFORE
553enum Action { Move { distance: u32 }, Stop } 713enum Action { Move { distance: u32 }, Stop }
554 714
555fn handle(action: Action) { 715fn handle(action: Action) {
@@ -558,8 +718,10 @@ fn handle(action: Action) {
558 _ => (), 718 _ => (),
559 } 719 }
560} 720}
721```
561 722
562// AFTER 723.After
724```rust
563enum Action { Move { distance: u32 }, Stop } 725enum Action { Move { distance: u32 }, Stop }
564 726
565fn handle(action: Action) { 727fn handle(action: Action) {
@@ -570,28 +732,36 @@ fn handle(action: Action) {
570} 732}
571``` 733```
572 734
573## `move_bounds_to_where_clause` 735
736[discrete]
737=== `move_bounds_to_where_clause`
738**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_assists/src/handlers/move_bounds.rs#L10[move_bounds.rs]
574 739
575Moves inline type bounds to a where clause. 740Moves inline type bounds to a where clause.
576 741
742.Before
577```rust 743```rust
578// BEFORE
579fn apply<T, U, ┃F: FnOnce(T) -> U>(f: F, x: T) -> U { 744fn apply<T, U, ┃F: FnOnce(T) -> U>(f: F, x: T) -> U {
580 f(x) 745 f(x)
581} 746}
747```
582 748
583// AFTER 749.After
750```rust
584fn apply<T, U, F>(f: F, x: T) -> U where F: FnOnce(T) -> U { 751fn apply<T, U, F>(f: F, x: T) -> U where F: FnOnce(T) -> U {
585 f(x) 752 f(x)
586} 753}
587``` 754```
588 755
589## `move_guard_to_arm_body` 756
757[discrete]
758=== `move_guard_to_arm_body`
759**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_assists/src/handlers/move_guard.rs#L8[move_guard.rs]
590 760
591Moves match guard into match arm body. 761Moves match guard into match arm body.
592 762
763.Before
593```rust 764```rust
594// BEFORE
595enum Action { Move { distance: u32 }, Stop } 765enum Action { Move { distance: u32 }, Stop }
596 766
597fn handle(action: Action) { 767fn handle(action: Action) {
@@ -600,8 +770,10 @@ fn handle(action: Action) {
600 _ => (), 770 _ => (),
601 } 771 }
602} 772}
773```
603 774
604// AFTER 775.After
776```rust
605enum Action { Move { distance: u32 }, Stop } 777enum Action { Move { distance: u32 }, Stop }
606 778
607fn handle(action: Action) { 779fn handle(action: Action) {
@@ -612,75 +784,98 @@ fn handle(action: Action) {
612} 784}
613``` 785```
614 786
615## `remove_dbg` 787
788[discrete]
789=== `remove_dbg`
790**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_assists/src/handlers/remove_dbg.rs#L8[remove_dbg.rs]
616 791
617Removes `dbg!()` macro call. 792Removes `dbg!()` macro call.
618 793
794.Before
619```rust 795```rust
620// BEFORE
621fn main() { 796fn main() {
622 ┃dbg!(92); 797 ┃dbg!(92);
623} 798}
799```
624 800
625// AFTER 801.After
802```rust
626fn main() { 803fn main() {
627 92; 804 92;
628} 805}
629``` 806```
630 807
631## `remove_hash` 808
809[discrete]
810=== `remove_hash`
811**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_assists/src/handlers/raw_string.rs#L89[raw_string.rs]
632 812
633Removes a hash from a raw string literal. 813Removes a hash from a raw string literal.
634 814
815.Before
635```rust 816```rust
636// BEFORE
637fn main() { 817fn main() {
638 r#"Hello,┃ World!"#; 818 r#"Hello,┃ World!"#;
639} 819}
820```
640 821
641// AFTER 822.After
823```rust
642fn main() { 824fn main() {
643 r"Hello, World!"; 825 r"Hello, World!";
644} 826}
645``` 827```
646 828
647## `remove_mut` 829
830[discrete]
831=== `remove_mut`
832**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_assists/src/handlers/remove_mut.rs#L5[remove_mut.rs]
648 833
649Removes the `mut` keyword. 834Removes the `mut` keyword.
650 835
836.Before
651```rust 837```rust
652// BEFORE
653impl Walrus { 838impl Walrus {
654 fn feed(&mut┃ self, amount: u32) {} 839 fn feed(&mut┃ self, amount: u32) {}
655} 840}
841```
656 842
657// AFTER 843.After
844```rust
658impl Walrus { 845impl Walrus {
659 fn feed(&self, amount: u32) {} 846 fn feed(&self, amount: u32) {}
660} 847}
661``` 848```
662 849
663## `reorder_fields` 850
851[discrete]
852=== `reorder_fields`
853**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_assists/src/handlers/reorder_fields.rs#L10[reorder_fields.rs]
664 854
665Reorder the fields of record literals and record patterns in the same order as in 855Reorder the fields of record literals and record patterns in the same order as in
666the definition. 856the definition.
667 857
858.Before
668```rust 859```rust
669// BEFORE
670struct Foo {foo: i32, bar: i32}; 860struct Foo {foo: i32, bar: i32};
671const test: Foo = ┃Foo {bar: 0, foo: 1} 861const test: Foo = ┃Foo {bar: 0, foo: 1}
862```
672 863
673// AFTER 864.After
865```rust
674struct Foo {foo: i32, bar: i32}; 866struct Foo {foo: i32, bar: i32};
675const test: Foo = Foo {foo: 1, bar: 0} 867const test: Foo = Foo {foo: 1, bar: 0}
676``` 868```
677 869
678## `replace_if_let_with_match` 870
871[discrete]
872=== `replace_if_let_with_match`
873**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_assists/src/handlers/replace_if_let_with_match.rs#L13[replace_if_let_with_match.rs]
679 874
680Replaces `if let` with an else branch with a `match` expression. 875Replaces `if let` with an else branch with a `match` expression.
681 876
877.Before
682```rust 878```rust
683// BEFORE
684enum Action { Move { distance: u32 }, Stop } 879enum Action { Move { distance: u32 }, Stop }
685 880
686fn handle(action: Action) { 881fn handle(action: Action) {
@@ -690,8 +885,10 @@ fn handle(action: Action) {
690 bar() 885 bar()
691 } 886 }
692} 887}
888```
693 889
694// AFTER 890.After
891```rust
695enum Action { Move { distance: u32 }, Stop } 892enum Action { Move { distance: u32 }, Stop }
696 893
697fn handle(action: Action) { 894fn handle(action: Action) {
@@ -702,20 +899,25 @@ fn handle(action: Action) {
702} 899}
703``` 900```
704 901
705## `replace_let_with_if_let` 902
903[discrete]
904=== `replace_let_with_if_let`
905**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_assists/src/handlers/replace_let_with_if_let.rs#L14[replace_let_with_if_let.rs]
706 906
707Replaces `let` with an `if-let`. 907Replaces `let` with an `if-let`.
708 908
909.Before
709```rust 910```rust
710// BEFORE
711 911
712fn main(action: Action) { 912fn main(action: Action) {
713 ┃let x = compute(); 913 ┃let x = compute();
714} 914}
715 915
716fn compute() -> Option<i32> { None } 916fn compute() -> Option<i32> { None }
917```
717 918
718// AFTER 919.After
920```rust
719 921
720fn main(action: Action) { 922fn main(action: Action) {
721 if let Some(x) = compute() { 923 if let Some(x) = compute() {
@@ -725,33 +927,43 @@ fn main(action: Action) {
725fn compute() -> Option<i32> { None } 927fn compute() -> Option<i32> { None }
726``` 928```
727 929
728## `replace_qualified_name_with_use` 930
931[discrete]
932=== `replace_qualified_name_with_use`
933**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_assists/src/handlers/replace_qualified_name_with_use.rs#L6[replace_qualified_name_with_use.rs]
729 934
730Adds a use statement for a given fully-qualified name. 935Adds a use statement for a given fully-qualified name.
731 936
937.Before
732```rust 938```rust
733// BEFORE
734fn process(map: std::collections::┃HashMap<String, String>) {} 939fn process(map: std::collections::┃HashMap<String, String>) {}
940```
735 941
736// AFTER 942.After
943```rust
737use std::collections::HashMap; 944use std::collections::HashMap;
738 945
739fn process(map: HashMap<String, String>) {} 946fn process(map: HashMap<String, String>) {}
740``` 947```
741 948
742## `replace_unwrap_with_match` 949
950[discrete]
951=== `replace_unwrap_with_match`
952**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_assists/src/handlers/replace_unwrap_with_match.rs#L17[replace_unwrap_with_match.rs]
743 953
744Replaces `unwrap` a `match` expression. Works for Result and Option. 954Replaces `unwrap` a `match` expression. Works for Result and Option.
745 955
956.Before
746```rust 957```rust
747// BEFORE
748enum Result<T, E> { Ok(T), Err(E) } 958enum Result<T, E> { Ok(T), Err(E) }
749fn main() { 959fn main() {
750 let x: Result<i32, i32> = Result::Ok(92); 960 let x: Result<i32, i32> = Result::Ok(92);
751 let y = x.┃unwrap(); 961 let y = x.┃unwrap();
752} 962}
963```
753 964
754// AFTER 965.After
966```rust
755enum Result<T, E> { Ok(T), Err(E) } 967enum Result<T, E> { Ok(T), Err(E) }
756fn main() { 968fn main() {
757 let x: Result<i32, i32> = Result::Ok(92); 969 let x: Result<i32, i32> = Result::Ok(92);
@@ -762,31 +974,41 @@ fn main() {
762} 974}
763``` 975```
764 976
765## `split_import` 977
978[discrete]
979=== `split_import`
980**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_assists/src/handlers/split_import.rs#L7[split_import.rs]
766 981
767Wraps the tail of import into braces. 982Wraps the tail of import into braces.
768 983
984.Before
769```rust 985```rust
770// BEFORE
771use std::┃collections::HashMap; 986use std::┃collections::HashMap;
987```
772 988
773// AFTER 989.After
990```rust
774use std::{collections::HashMap}; 991use std::{collections::HashMap};
775``` 992```
776 993
777## `unwrap_block` 994
995[discrete]
996=== `unwrap_block`
997**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_assists/src/handlers/unwrap_block.rs#L9[unwrap_block.rs]
778 998
779This assist removes if...else, for, while and loop control statements to just keep the body. 999This assist removes if...else, for, while and loop control statements to just keep the body.
780 1000
1001.Before
781```rust 1002```rust
782// BEFORE
783fn foo() { 1003fn foo() {
784 if true {┃ 1004 if true {┃
785 println!("foo"); 1005 println!("foo");
786 } 1006 }
787} 1007}
1008```
788 1009
789// AFTER 1010.After
1011```rust
790fn foo() { 1012fn foo() {
791 println!("foo"); 1013 println!("foo");
792} 1014}
diff --git a/docs/user/generated_features.adoc b/docs/user/generated_features.adoc
new file mode 100644
index 000000000..12812fa0b
--- /dev/null
+++ b/docs/user/generated_features.adoc
@@ -0,0 +1,298 @@
1=== Expand Macro Recursively
2**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_ide/src/expand_macro.rs#L15[expand_macro.rs]
3
4Shows the full macro expansion of the macro at current cursor.
5
6|===
7| Editor | Action Name
8
9| VS Code | **Rust Analyzer: Expand macro recursively**
10|===
11
12
13=== Extend Selection
14**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_ide/src/extend_selection.rs#L15[extend_selection.rs]
15
16Extends the current selection to the encompassing syntactic construct
17(expression, statement, item, module, etc). It works with multiple cursors.
18
19|===
20| Editor | Shortcut
21
22| VS Code | kbd:[Ctrl+Shift+→]
23|===
24
25
26=== File Structure
27**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_ide/src/display/structure.rs#L17[structure.rs]
28
29Provides a tree of the symbols defined in the file. Can be used to
30
31* fuzzy search symbol in a file (super useful)
32* draw breadcrumbs to describe the context around the cursor
33* draw outline of the file
34
35|===
36| Editor | Shortcut
37
38| VS Code | kbd:[Ctrl+Shift+O]
39|===
40
41
42=== Go to Definition
43**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_ide/src/goto_definition.rs#L18[goto_definition.rs]
44
45Navigates to the definition of an identifier.
46
47|===
48| Editor | Shortcut
49
50| VS Code | kbd:[F12]
51|===
52
53
54=== Go to Implementation
55**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_ide/src/goto_implementation.rs#L7[goto_implementation.rs]
56
57Navigates to the impl block of structs, enums or traits. Also implemented as a code lens.
58
59|===
60| Editor | Shortcut
61
62| VS Code | kbd:[Ctrl+F12]
63|===
64
65
66=== Go to Type Definition
67**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_ide/src/goto_type_definition.rs#L6[goto_type_definition.rs]
68
69Navigates to the type of an identifier.
70
71|===
72| Editor | Action Name
73
74| VS Code | **Go to Type Definition*
75|===
76
77
78=== Hover
79**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_ide/src/hover.rs#L63[hover.rs]
80
81Shows additional information, like type of an expression or documentation for definition when "focusing" code.
82Focusing is usually hovering with a mouse, but can also be triggered with a shortcut.
83
84
85=== Inlay Hints
86**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_ide/src/inlay_hints.rs#L40[inlay_hints.rs]
87
88rust-analyzer shows additional information inline with the source code.
89Editors usually render this using read-only virtual text snippets interspersed with code.
90
91rust-analyzer shows hits for
92
93* types of local variables
94* names of function arguments
95* types of chained expressions
96
97**Note:** VS Code does not have native support for inlay hints https://github.com/microsoft/vscode/issues/16221[yet] and the hints are implemented using decorations.
98This approach has limitations, the caret movement and bracket highlighting near the edges of the hint may be weird:
99https://github.com/rust-analyzer/rust-analyzer/issues/1623[1], https://github.com/rust-analyzer/rust-analyzer/issues/3453[2].
100
101|===
102| Editor | Action Name
103
104| VS Code | **Rust Analyzer: Toggle inlay hints*
105|===
106
107
108=== Join Lines
109**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_ide/src/join_lines.rs#L12[join_lines.rs]
110
111Join selected lines into one, smartly fixing up whitespace, trailing commas, and braces.
112
113|===
114| Editor | Action Name
115
116| VS Code | **Rust Analyzer: Join lines**
117|===
118
119
120=== Magic Completions
121**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_ide/src/completion.rs#L38[completion.rs]
122
123In addition to usual reference completion, rust-analyzer provides some ✨magic✨
124completions as well:
125
126Keywords like `if`, `else` `while`, `loop` are completed with braces, and cursor
127is placed at the appropriate position. Even though `if` is easy to type, you
128still want to complete it, to get ` { }` for free! `return` is inserted with a
129space or `;` depending on the return type of the function.
130
131When completing a function call, `()` are automatically inserted. If a function
132takes arguments, the cursor is positioned inside the parenthesis.
133
134There are postfix completions, which can be triggered by typing something like
135`foo().if`. The word after `.` determines postfix completion. Possible variants are:
136
137- `expr.if` -> `if expr {}` or `if let ... {}` for `Option` or `Result`
138- `expr.match` -> `match expr {}`
139- `expr.while` -> `while expr {}` or `while let ... {}` for `Option` or `Result`
140- `expr.ref` -> `&expr`
141- `expr.refm` -> `&mut expr`
142- `expr.not` -> `!expr`
143- `expr.dbg` -> `dbg!(expr)`
144
145There also snippet completions:
146
147.Expressions
148- `pd` -> `println!("{:?}")`
149- `ppd` -> `println!("{:#?}")`
150
151.Items
152- `tfn` -> `#[test] fn f(){}`
153- `tmod` ->
154```rust
155#[cfg(test)]
156mod tests {
157 use super::*;
158
159 #[test]
160 fn test_fn() {}
161}
162```
163
164
165=== Matching Brace
166**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_ide/src/matching_brace.rs#L3[matching_brace.rs]
167
168If the cursor is on any brace (`<>(){}[]`) which is a part of a brace-pair,
169moves cursor to the matching brace. It uses the actual parser to determine
170braces, so it won't confuse generics with comparisons.
171
172|===
173| Editor | Action Name
174
175| VS Code | **Rust Analyzer: Find matching brace**
176|===
177
178
179=== On Typing Assists
180**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_ide/src/typing.rs#L35[typing.rs]
181
182Some features trigger on typing certain characters:
183
184- typing `let =` tries to smartly add `;` if `=` is followed by an existing expression
185- Enter inside comments automatically inserts `///`
186- typing `.` in a chain method call auto-indents
187
188
189=== Parent Module
190**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_ide/src/parent_module.rs#L12[parent_module.rs]
191
192Navigates to the parent module of the current module.
193
194|===
195| Editor | Action Name
196
197| VS Code | **Rust Analyzer: Locate parent module**
198|===
199
200
201=== Run
202**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_ide/src/runnables.rs#L45[runnables.rs]
203
204Shows a popup suggesting to run a test/benchmark/binary **at the current cursor
205location**. Super useful for repeatedly running just a single test. Do bind this
206to a shortcut!
207
208|===
209| Editor | Action Name
210
211| VS Code | **Rust Analyzer: Run**
212|===
213
214
215=== Semantic Syntax Highlighting
216**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_ide/src/syntax_highlighting.rs#L33[syntax_highlighting.rs]
217
218rust-analyzer highlights the code semantically.
219For example, `bar` in `foo::Bar` might be colored differently depending on whether `Bar` is an enum or a trait.
220rust-analyzer does not specify colors directly, instead it assigns tag (like `struct`) and a set of modifiers (like `declaration`) to each token.
221It's up to the client to map those to specific colors.
222
223The general rule is that a reference to an entity gets colored the same way as the entity itself.
224We also give special modifier for `mut` and `&mut` local variables.
225
226
227=== Show Syntax Tree
228**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_ide/src/syntax_tree.rs#L9[syntax_tree.rs]
229
230Shows the parse tree of the current file. It exists mostly for debugging
231rust-analyzer itself.
232
233|===
234| Editor | Action Name
235
236| VS Code | **Rust Analyzer: Show Syntax Tree**
237|===
238
239
240=== Status
241**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_ide/src/status.rs#L27[status.rs]
242
243Shows internal statistic about memory usage of rust-analyzer.
244
245|===
246| Editor | Action Name
247
248| VS Code | **Rust Analyzer: Status**
249|===
250
251
252=== Structural Seach and Replace
253**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_ide/src/ssr.rs#L26[ssr.rs]
254
255Search and replace with named wildcards that will match any expression.
256The syntax for a structural search replace command is `<search_pattern> ==>> <replace_pattern>`.
257A `$<name>:expr` placeholder in the search pattern will match any expression and `$<name>` will reference it in the replacement.
258Available via the command `rust-analyzer.ssr`.
259
260```rust
261// Using structural search replace command [foo($a:expr, $b:expr) ==>> ($a).foo($b)]
262
263// BEFORE
264String::from(foo(y + 5, z))
265
266// AFTER
267String::from((y + 5).foo(z))
268```
269
270|===
271| Editor | Action Name
272
273| VS Code | **Rust Analyzer: Structural Search Replace**
274|===
275
276
277=== Workspace Symbol
278**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_ide_db/src/symbol_index.rs#L113[symbol_index.rs]
279
280Uses fuzzy-search to find types, modules and functions by name across your
281project and dependencies. This is **the** most useful feature, which improves code
282navigation tremendously. It mostly works on top of the built-in LSP
283functionality, however `#` and `*` symbols can be used to narrow down the
284search. Specifically,
285
286- `Foo` searches for `Foo` type in the current workspace
287- `foo#` searches for `foo` function in the current workspace
288- `Foo*` searches for `Foo` type among dependencies, including `stdlib`
289- `foo#*` searches for `foo` function among dependencies
290
291That is, `#` switches from "types" to all symbols, `*` switches from the current
292workspace to dependencies.
293
294|===
295| Editor | Shortcut
296
297| VS Code | kbd:[Ctrl+T]
298|===
diff --git a/docs/user/readme.adoc b/docs/user/manual.adoc
index 64bd0feb1..202783fd9 100644
--- a/docs/user/readme.adoc
+++ b/docs/user/manual.adoc
@@ -2,12 +2,9 @@
2:toc: preamble 2:toc: preamble
3:sectanchors: 3:sectanchors:
4:page-layout: post 4:page-layout: post
5// https://gist.github.com/dcode/0cfbf2699a1fe9b46ff04c41721dda74#admonitions 5:icons: font
6:tip-caption: :bulb: 6:source-highlighter: rouge
7:note-caption: :information_source: 7:experimental:
8:important-caption: :heavy_exclamation_mark:
9:caution-caption: :fire:
10:warning-caption: :warning:
11 8
12// Master copy of this document lives in the https://github.com/rust-analyzer/rust-analyzer repository 9// Master copy of this document lives in the https://github.com/rust-analyzer/rust-analyzer repository
13 10
@@ -17,7 +14,7 @@ https://microsoft.github.io/language-server-protocol/[Language Server Protocol]
17The 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. 14The 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.
18 15
19To improve this document, send a pull request against 16To improve this document, send a pull request against
20https://github.com/rust-analyzer/rust-analyzer/blob/master/docs/user/readme.adoc[this file]. 17https://github.com/rust-analyzer/rust-analyzer/blob/master/docs/user/manual.adoc[this file].
21 18
22If you have questions about using rust-analyzer, please ask them in the https://users.rust-lang.org/c/ide/14["`IDEs and Editors`"] topic of Rust users forum. 19If you have questions about using rust-analyzer, please ask them in the https://users.rust-lang.org/c/ide/14["`IDEs and Editors`"] topic of Rust users forum.
23 20
@@ -65,16 +62,6 @@ The server binary is stored in:
65 62
66Note that we only support two most recent versions of VS Code. 63Note that we only support two most recent versions of VS Code.
67 64
68==== Special `when` clause context for keybindings.
69You may use `inRustProject` context to configure keybindings for rust projects only. For example:
70[source,json]
71----
72{ "key": "ctrl+shift+f5", "command": "workbench.action.debug.restart", "when": "inDebugMode && !inRustProject"},
73{ "key": "ctrl+shift+f5", "command": "rust-analyzer.debug", "when": "inRustProject"},
74{ "key": "ctrl+i", "command": "rust-analyzer.toggleInlayHints", "when": "inRustProject" }
75----
76More about `when` clause contexts https://code.visualstudio.com/docs/getstarted/keybindings#_when-clause-contexts[here].
77
78==== Updates 65==== Updates
79 66
80The extension will be updated automatically as new versions become available. It will ask your permission to download the matching language server version binary if needed. 67The extension will be updated automatically as new versions become available. It will ask your permission to download the matching language server version binary if needed.
@@ -122,10 +109,23 @@ Here are some useful self-diagnostic commands:
122* To log all LSP requests, add `"rust-analyzer.trace.server": "verbose"` to the settings and look for `Server Trace` in the panel. 109* To log all LSP requests, add `"rust-analyzer.trace.server": "verbose"` to the settings and look for `Server Trace` in the panel.
123* To enable client-side logging, add `"rust-analyzer.trace.extension": true` to the settings and open the `Console` tab of VS Code developer tools. 110* To enable client-side logging, add `"rust-analyzer.trace.extension": true` to the settings and open the `Console` tab of VS Code developer tools.
124 111
112==== Special `when` clause context for keybindings.
113You may use `inRustProject` context to configure keybindings for rust projects only. For example:
114[source,json]
115----
116{
117 "key": "ctrl+i",
118 "command": "rust-analyzer.toggleInlayHints",
119 "when": "inRustProject"
120}
121----
122More about `when` clause contexts https://code.visualstudio.com/docs/getstarted/keybindings#_when-clause-contexts[here].
123
125=== rust-analyzer Language Server Binary 124=== rust-analyzer Language Server Binary
126 125
127Other editors generally require the `rust-analyzer` binary to be in `$PATH`. 126Other editors generally require the `rust-analyzer` binary to be in `$PATH`.
128You can download the pre-built binary from the https://github.com/rust-analyzer/rust-analyzer/releases[releases] page. Typically, you then need to rename the binary for your platform, e.g. `rust-analyzer-mac` if you're on Mac OS, to `rust-analyzer` and make it executable in addition to moving it into a directory in your `$PATH`. 127You can download the pre-built binary from the https://github.com/rust-analyzer/rust-analyzer/releases[releases] page.
128Typically, you then need to rename the binary for your platform, e.g. `rust-analyzer-mac` if you're on Mac OS, to `rust-analyzer` and make it executable in addition to moving it into a directory in your `$PATH`.
129 129
130On Linux to install the `rust-analyzer` binary into `~/.local/bin`, this commands could be used 130On Linux to install the `rust-analyzer` binary into `~/.local/bin`, this commands could be used
131 131
@@ -145,7 +145,8 @@ $ git clone https://github.com/rust-analyzer/rust-analyzer.git && cd rust-analyz
145$ cargo xtask install --server 145$ cargo xtask install --server
146---- 146----
147 147
148If your editor can't find the binary even though the binary is on your `$PATH`, the likely explanation is that it doesn't see the same `$PATH` as the shell, see https://github.com/rust-analyzer/rust-analyzer/issues/1811[this issue]. On Unix, running the editor from a shell or changing the `.desktop` file to set the environment should help. 148If your editor can't find the binary even though the binary is on your `$PATH`, the likely explanation is that it doesn't see the same `$PATH` as the shell, see https://github.com/rust-analyzer/rust-analyzer/issues/1811[this issue].
149On Unix, running the editor from a shell or changing the `.desktop` file to set the environment should help.
149 150
150==== Arch Linux 151==== Arch Linux
151 152
@@ -268,6 +269,14 @@ Gnome Builder currently has support for RLS, and there's no way to configure the
2681. Rename, symlink or copy the `rust-analyzer` binary to `rls` and place it somewhere Builder can find (in `PATH`, or under `~/.cargo/bin`). 2691. Rename, symlink or copy the `rust-analyzer` binary to `rls` and place it somewhere Builder can find (in `PATH`, or under `~/.cargo/bin`).
2692. Enable the Rust Builder plugin. 2702. Enable the Rust Builder plugin.
270 271
271== Usage 272== Features
273
274include::./generated_features.adoc[]
275
276== Assists (Code Actions)
277
278Assists, or code actions, are small local refactorings, available in a particular context.
279They are usually triggered by a shortcut or by clicking a light bulb icon in the editor.
280Cursor position or selection is signified by `┃` character.
272 281
273See https://github.com/rust-analyzer/rust-analyzer/blob/master/docs/user/features.md[features.md]. 282include::./generated_assists.adoc[]
generated by cgit v1.2.3 (git 2.25.1) at 2024-11-04 21:26:19 +0000