aboutsummaryrefslogtreecommitdiff
path: root/docs
diff options
context:
space:
mode:
Diffstat (limited to 'docs')
-rw-r--r--docs/dev/README.md105
-rw-r--r--docs/dev/lsp-extensions.md92
-rw-r--r--docs/dev/lsp-features.md72
-rw-r--r--docs/user/assists.md769
-rw-r--r--docs/user/features.md218
-rw-r--r--docs/user/generated_assists.adoc1015
-rw-r--r--docs/user/generated_features.adoc298
-rw-r--r--docs/user/manual.adoc (renamed from docs/user/readme.adoc)51
8 files changed, 1502 insertions, 1118 deletions
diff --git a/docs/dev/README.md b/docs/dev/README.md
index 65cc9fc12..1de5a2aab 100644
--- a/docs/dev/README.md
+++ b/docs/dev/README.md
@@ -30,7 +30,7 @@ https://rust-lang.zulipchat.com/#narrow/stream/185405-t-compiler.2Fwg-rls-2.2E0
30 30
31* [good-first-issue](https://github.com/rust-analyzer/rust-analyzer/labels/good%20first%20issue) 31* [good-first-issue](https://github.com/rust-analyzer/rust-analyzer/labels/good%20first%20issue)
32 are good issues to get into the project. 32 are good issues to get into the project.
33* [E-mentor](https://github.com/rust-analyzer/rust-analyzer/issues?q=is%3Aopen+is%3Aissue+label%3AE-mentor) 33* [E-has-instructions](https://github.com/rust-analyzer/rust-analyzer/issues?q=is%3Aopen+is%3Aissue+label%3AE-has-instructions)
34 issues have links to the code in question and tests. 34 issues have links to the code in question and tests.
35* [E-easy](https://github.com/rust-analyzer/rust-analyzer/issues?q=is%3Aopen+is%3Aissue+label%3AE-easy), 35* [E-easy](https://github.com/rust-analyzer/rust-analyzer/issues?q=is%3Aopen+is%3Aissue+label%3AE-easy),
36 [E-medium](https://github.com/rust-analyzer/rust-analyzer/issues?q=is%3Aopen+is%3Aissue+label%3AE-medium), 36 [E-medium](https://github.com/rust-analyzer/rust-analyzer/issues?q=is%3Aopen+is%3Aissue+label%3AE-medium),
@@ -117,6 +117,109 @@ Additionally, I use `cargo run --release -p rust-analyzer -- analysis-stats
117path/to/some/rust/crate` to run a batch analysis. This is primarily useful for 117path/to/some/rust/crate` to run a batch analysis. This is primarily useful for
118performance optimizations, or for bug minimization. 118performance optimizations, or for bug minimization.
119 119
120# Code Style & Review Process
121
122Our approach to "clean code" is two fold:
123
124* We generally don't block PRs on style changes.
125* At the same time, all code in rust-analyzer is constantly refactored.
126
127It is explicitly OK for reviewer to flag only some nits in the PR, and than send a follow up cleanup PR for things which are easier to explain by example, cc-ing the original author.
128Sending small cleanup PRs (like rename a single local variable) is encouraged.
129
130## Scale of Changes
131
132Everyone knows that it's better to send small & focused pull requests.
133The problem is, sometimes you *have* to, eg, rewrite the whole compiler, and that just doesn't fit into a set of isolated PRs.
134
135The main thing too keep an eye on is the boundaries between various components.
136There are three kinds of changes:
137
1381. Internals of a single component are changed.
139 Specifically, you don't change any `pub` items.
140 A good example here would be an addition of a new assist.
141
1422. API of a component is expanded.
143 Specifically, you add a new `pub` function which wasn't there before.
144 A good example here would be expansion of assist API, for example, to implement lazy assists or assists groups.
145
1463. A new dependency between components is introduced.
147 Specifically, you add a `pub use` reexport from another crate or you add a new line to `[dependencies]` section of `Cargo.toml`.
148 A good example here would be adding reference search capability to the assists crates.
149
150For the first group, the change is generally merged as long as:
151
152* it works for the happy case,
153* it has tests,
154* it doesn't panic for unhappy case.
155
156For the second group, the change would be subjected to quite a bit of scrutiny and iteration.
157The new API needs to be right (or at least easy to change later).
158The actual implementation doesn't matter that much.
159It's very important to minimize the amount of changed lines of code for changes of the second kind.
160Often, you start doing change of the first kind, only to realise that you need to elevate to a change of the second kind.
161In this case, we'll probably ask you to split API changes into a separate PR.
162
163Changes of the third group should be pretty rare, so we don't specify any specific process for them.
164That said, adding an innocent-looking `pub use` is a very simple way to break encapsulation, keep an eye on it!
165
166Note: if you enjoyed this abstract hand-waving about boundaries, you might appreciate
167https://www.tedinski.com/2018/02/06/system-boundaries.html
168
169## Order of Imports
170
171We separate import groups with blank lines
172
173```
174mod x;
175mod y;
176
177use std::{ ... }
178
179use crate_foo::{ ... }
180use crate_bar::{ ... }
181
182use crate::{}
183
184use super::{} // but prefer `use crate::`
185```
186
187## Order of Items
188
189Optimize for the reader who sees the file for the first time, and wants to get the general idea about what's going on.
190People read things from top to bottom, so place most important things first.
191
192Specifically, if all items except one are private, always put the non-private item on top.
193
194Put `struct`s and `enum`s first, functions and impls last.
195
196Do
197
198```
199// Good
200struct Foo {
201 bars: Vec<Bar>
202}
203
204struct Bar;
205```
206
207rather than
208
209```
210// Not as good
211struct Bar;
212
213struct Foo {
214 bars: Vec<Bar>
215}
216```
217
218## Documentation
219
220For `.md` and `.adoc` files, prefer a sentence-per-line format, don't wrap lines.
221If the line is too long, you want to split the sentence in two :-)
222
120# Logging 223# Logging
121 224
122Logging is done by both rust-analyzer and VS Code, so it might be tricky to 225Logging is done by both rust-analyzer and VS Code, so it might be tricky to
diff --git a/docs/dev/lsp-extensions.md b/docs/dev/lsp-extensions.md
index 68a5df27e..647cf6107 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
@@ -154,7 +164,7 @@ fn main() {
154} 164}
155``` 165```
156 166
157`experimental/joinLines` yields (curly braces are automagiacally removed) 167`experimental/joinLines` yields (curly braces are automagically removed)
158 168
159```rust 169```rust
160fn main() { 170fn main() {
@@ -301,6 +311,50 @@ Moreover, it would be cool if editors didn't need to implement even basic langua
301 This is how `SelectionRange` request works. 311 This is how `SelectionRange` request works.
302* Alternatively, should we perhaps flag certain `SelectionRange`s as being brace pairs? 312* Alternatively, should we perhaps flag certain `SelectionRange`s as being brace pairs?
303 313
314## Runnables
315
316**Issue:** https://github.com/microsoft/language-server-protocol/issues/944
317
318**Server Capability:** `{ "runnables": { "kinds": string[] } }`
319
320This request is send from client to server to get the list of things that can be run (tests, binaries, `cargo check -p`).
321
322**Method:** `experimental/runnables`
323
324**Request:**
325
326```typescript
327interface RunnablesParams {
328 textDocument: TextDocumentIdentifier;
329 /// If null, compute runnables for the whole file.
330 position?: Position;
331}
332```
333
334**Response:** `Runnable[]`
335
336```typescript
337interface Runnable {
338 label: string;
339 /// If this Runnable is associated with a specific function/module, etc, the location of this item
340 location?: LocationLink;
341 /// Running things is necessary technology specific, `kind` needs to be advertised via server capabilities,
342 // the type of `args` is specific to `kind`. The actual running is handled by the client.
343 kind: string;
344 args: any;
345}
346```
347
348rust-analyzer supports only one `kind`, `"cargo"`. The `args` for `"cargo"` look like this:
349
350```typescript
351{
352 workspaceRoot?: string;
353 cargoArgs: string[];
354 executableArgs: string[];
355}
356```
357
304## Analyzer Status 358## Analyzer Status
305 359
306**Method:** `rust-analyzer/analyzerStatus` 360**Method:** `rust-analyzer/analyzerStatus`
@@ -389,39 +443,3 @@ interface InlayHint {
389 label: string, 443 label: string,
390} 444}
391``` 445```
392
393## Runnables
394
395**Method:** `rust-analyzer/runnables`
396
397This request is send from client to server to get the list of things that can be run (tests, binaries, `cargo check -p`).
398Note that we plan to move this request to `experimental/runnables`, as it is not really Rust-specific, but the current API is not necessary the right one.
399Upstream issue: https://github.com/microsoft/language-server-protocol/issues/944
400
401**Request:**
402
403```typescript
404interface RunnablesParams {
405 textDocument: TextDocumentIdentifier;
406 /// If null, compute runnables for the whole file.
407 position?: Position;
408}
409```
410
411**Response:** `Runnable[]`
412
413```typescript
414interface Runnable {
415 /// The range this runnable is applicable for.
416 range: lc.Range;
417 /// The label to show in the UI.
418 label: string;
419 /// The following fields describe a process to spawn.
420 bin: string;
421 args: string[];
422 /// Args for cargo after `--`.
423 extraArgs: string[];
424 env: { [key: string]: string };
425 cwd: string | null;
426}
427```
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/assists.md b/docs/user/assists.md
deleted file mode 100644
index 4ad7ea59d..000000000
--- a/docs/user/assists.md
+++ /dev/null
@@ -1,769 +0,0 @@
1# Assists
2
3Cursor position or selection is signified by `┃` character.
4
5
6## `add_custom_impl`
7
8Adds impl block for derived trait.
9
10```rust
11// BEFORE
12#[derive(Deb┃ug, Display)]
13struct S;
14
15// AFTER
16#[derive(Display)]
17struct S;
18
19impl Debug for S {
20 $0
21}
22```
23
24## `add_derive`
25
26Adds a new `#[derive()]` clause to a struct or enum.
27
28```rust
29// BEFORE
30struct Point {
31 x: u32,
32 y: u32,┃
33}
34
35// AFTER
36#[derive($0)]
37struct Point {
38 x: u32,
39 y: u32,
40}
41```
42
43## `add_explicit_type`
44
45Specify type for a let binding.
46
47```rust
48// BEFORE
49fn main() {
50 let x┃ = 92;
51}
52
53// AFTER
54fn main() {
55 let x: i32 = 92;
56}
57```
58
59## `add_function`
60
61Adds a stub function with a signature matching the function under the cursor.
62
63```rust
64// BEFORE
65struct Baz;
66fn baz() -> Baz { Baz }
67fn foo() {
68 bar┃("", baz());
69}
70
71
72// AFTER
73struct Baz;
74fn baz() -> Baz { Baz }
75fn foo() {
76 bar("", baz());
77}
78
79fn bar(arg: &str, baz: Baz) {
80 ${0:todo!()}
81}
82
83```
84
85## `add_hash`
86
87Adds a hash to a raw string literal.
88
89```rust
90// BEFORE
91fn main() {
92 r#"Hello,┃ World!"#;
93}
94
95// AFTER
96fn main() {
97 r##"Hello, World!"##;
98}
99```
100
101## `add_impl`
102
103Adds a new inherent impl for a type.
104
105```rust
106// BEFORE
107struct Ctx<T: Clone> {
108 data: T,┃
109}
110
111// AFTER
112struct Ctx<T: Clone> {
113 data: T,
114}
115
116impl<T: Clone> Ctx<T> {
117 $0
118}
119```
120
121## `add_impl_default_members`
122
123Adds scaffold for overriding default impl members.
124
125```rust
126// BEFORE
127trait Trait {
128 Type X;
129 fn foo(&self);
130 fn bar(&self) {}
131}
132
133impl Trait for () {
134 Type X = ();
135 fn foo(&self) {}┃
136
137}
138
139// AFTER
140trait Trait {
141 Type X;
142 fn foo(&self);
143 fn bar(&self) {}
144}
145
146impl Trait for () {
147 Type X = ();
148 fn foo(&self) {}
149 $0fn bar(&self) {}
150
151}
152```
153
154## `add_impl_missing_members`
155
156Adds scaffold for required impl members.
157
158```rust
159// BEFORE
160trait Trait<T> {
161 Type X;
162 fn foo(&self) -> T;
163 fn bar(&self) {}
164}
165
166impl Trait<u32> for () {┃
167
168}
169
170// AFTER
171trait Trait<T> {
172 Type X;
173 fn foo(&self) -> T;
174 fn bar(&self) {}
175}
176
177impl Trait<u32> for () {
178 fn foo(&self) -> u32 {
179 ${0:todo!()}
180 }
181
182}
183```
184
185## `add_new`
186
187Adds a new inherent impl for a type.
188
189```rust
190// BEFORE
191struct Ctx<T: Clone> {
192 data: T,┃
193}
194
195// AFTER
196struct Ctx<T: Clone> {
197 data: T,
198}
199
200impl<T: Clone> Ctx<T> {
201 fn $0new(data: T) -> Self { Self { data } }
202}
203
204```
205
206## `add_turbo_fish`
207
208Adds `::<_>` to a call of a generic method or function.
209
210```rust
211// BEFORE
212fn make<T>() -> T { todo!() }
213fn main() {
214 let x = make┃();
215}
216
217// AFTER
218fn make<T>() -> T { todo!() }
219fn main() {
220 let x = make::<${0:_}>();
221}
222```
223
224## `apply_demorgan`
225
226Apply [De Morgan's law](https://en.wikipedia.org/wiki/De_Morgan%27s_laws).
227This transforms expressions of the form `!l || !r` into `!(l && r)`.
228This also works with `&&`. This assist can only be applied with the cursor
229on either `||` or `&&`, with both operands being a negation of some kind.
230This means something of the form `!x` or `x != y`.
231
232```rust
233// BEFORE
234fn main() {
235 if x != 4 ||┃ !y {}
236}
237
238// AFTER
239fn main() {
240 if !(x == 4 && y) {}
241}
242```
243
244## `auto_import`
245
246If the name is unresolved, provides all possible imports for it.
247
248```rust
249// BEFORE
250fn main() {
251 let map = HashMap┃::new();
252}
253
254// AFTER
255use std::collections::HashMap;
256
257fn main() {
258 let map = HashMap::new();
259}
260```
261
262## `change_return_type_to_result`
263
264Change the function's return type to Result.
265
266```rust
267// BEFORE
268fn foo() -> i32┃ { 42i32 }
269
270// AFTER
271fn foo() -> Result<i32, ${0:_}> { Ok(42i32) }
272```
273
274## `change_visibility`
275
276Adds or changes existing visibility specifier.
277
278```rust
279// BEFORE
280┃fn frobnicate() {}
281
282// AFTER
283pub(crate) fn frobnicate() {}
284```
285
286## `convert_to_guarded_return`
287
288Replace a large conditional with a guarded return.
289
290```rust
291// BEFORE
292fn main() {
293 ┃if cond {
294 foo();
295 bar();
296 }
297}
298
299// AFTER
300fn main() {
301 if !cond {
302 return;
303 }
304 foo();
305 bar();
306}
307```
308
309## `fill_match_arms`
310
311Adds missing clauses to a `match` expression.
312
313```rust
314// BEFORE
315enum Action { Move { distance: u32 }, Stop }
316
317fn handle(action: Action) {
318 match action {
319 ┃
320 }
321}
322
323// AFTER
324enum Action { Move { distance: u32 }, Stop }
325
326fn handle(action: Action) {
327 match action {
328 $0Action::Move { distance } => {}
329 Action::Stop => {}
330 }
331}
332```
333
334## `fix_visibility`
335
336Makes inaccessible item public.
337
338```rust
339// BEFORE
340mod m {
341 fn frobnicate() {}
342}
343fn main() {
344 m::frobnicate┃() {}
345}
346
347// AFTER
348mod m {
349 $0pub(crate) fn frobnicate() {}
350}
351fn main() {
352 m::frobnicate() {}
353}
354```
355
356## `flip_binexpr`
357
358Flips operands of a binary expression.
359
360```rust
361// BEFORE
362fn main() {
363 let _ = 90 +┃ 2;
364}
365
366// AFTER
367fn main() {
368 let _ = 2 + 90;
369}
370```
371
372## `flip_comma`
373
374Flips two comma-separated items.
375
376```rust
377// BEFORE
378fn main() {
379 ((1, 2),┃ (3, 4));
380}
381
382// AFTER
383fn main() {
384 ((3, 4), (1, 2));
385}
386```
387
388## `flip_trait_bound`
389
390Flips two trait bounds.
391
392```rust
393// BEFORE
394fn foo<T: Clone +┃ Copy>() { }
395
396// AFTER
397fn foo<T: Copy + Clone>() { }
398```
399
400## `inline_local_variable`
401
402Inlines local variable.
403
404```rust
405// BEFORE
406fn main() {
407 let x┃ = 1 + 2;
408 x * 4;
409}
410
411// AFTER
412fn main() {
413 (1 + 2) * 4;
414}
415```
416
417## `introduce_variable`
418
419Extracts subexpression into a variable.
420
421```rust
422// BEFORE
423fn main() {
424 ┃(1 + 2)┃ * 4;
425}
426
427// AFTER
428fn main() {
429 let $0var_name = (1 + 2);
430 var_name * 4;
431}
432```
433
434## `invert_if`
435
436Apply invert_if
437This transforms if expressions of the form `if !x {A} else {B}` into `if x {B} else {A}`
438This also works with `!=`. This assist can only be applied with the cursor
439on `if`.
440
441```rust
442// BEFORE
443fn main() {
444 if┃ !y { A } else { B }
445}
446
447// AFTER
448fn main() {
449 if y { B } else { A }
450}
451```
452
453## `make_raw_string`
454
455Adds `r#` to a plain string literal.
456
457```rust
458// BEFORE
459fn main() {
460 "Hello,┃ World!";
461}
462
463// AFTER
464fn main() {
465 r#"Hello, World!"#;
466}
467```
468
469## `make_usual_string`
470
471Turns a raw string into a plain string.
472
473```rust
474// BEFORE
475fn main() {
476 r#"Hello,┃ "World!""#;
477}
478
479// AFTER
480fn main() {
481 "Hello, \"World!\"";
482}
483```
484
485## `merge_imports`
486
487Merges two imports with a common prefix.
488
489```rust
490// BEFORE
491use std::┃fmt::Formatter;
492use std::io;
493
494// AFTER
495use std::{fmt::Formatter, io};
496```
497
498## `merge_match_arms`
499
500Merges identical match arms.
501
502```rust
503// BEFORE
504enum Action { Move { distance: u32 }, Stop }
505
506fn handle(action: Action) {
507 match action {
508 ┃Action::Move(..) => foo(),
509 Action::Stop => foo(),
510 }
511}
512
513// AFTER
514enum Action { Move { distance: u32 }, Stop }
515
516fn handle(action: Action) {
517 match action {
518 Action::Move(..) | Action::Stop => foo(),
519 }
520}
521```
522
523## `move_arm_cond_to_match_guard`
524
525Moves if expression from match arm body into a guard.
526
527```rust
528// BEFORE
529enum Action { Move { distance: u32 }, Stop }
530
531fn handle(action: Action) {
532 match action {
533 Action::Move { distance } => ┃if distance > 10 { foo() },
534 _ => (),
535 }
536}
537
538// AFTER
539enum Action { Move { distance: u32 }, Stop }
540
541fn handle(action: Action) {
542 match action {
543 Action::Move { distance } if distance > 10 => foo(),
544 _ => (),
545 }
546}
547```
548
549## `move_bounds_to_where_clause`
550
551Moves inline type bounds to a where clause.
552
553```rust
554// BEFORE
555fn apply<T, U, ┃F: FnOnce(T) -> U>(f: F, x: T) -> U {
556 f(x)
557}
558
559// AFTER
560fn apply<T, U, F>(f: F, x: T) -> U where F: FnOnce(T) -> U {
561 f(x)
562}
563```
564
565## `move_guard_to_arm_body`
566
567Moves match guard into match arm body.
568
569```rust
570// BEFORE
571enum Action { Move { distance: u32 }, Stop }
572
573fn handle(action: Action) {
574 match action {
575 Action::Move { distance } ┃if distance > 10 => foo(),
576 _ => (),
577 }
578}
579
580// AFTER
581enum Action { Move { distance: u32 }, Stop }
582
583fn handle(action: Action) {
584 match action {
585 Action::Move { distance } => if distance > 10 { foo() },
586 _ => (),
587 }
588}
589```
590
591## `remove_dbg`
592
593Removes `dbg!()` macro call.
594
595```rust
596// BEFORE
597fn main() {
598 ┃dbg!(92);
599}
600
601// AFTER
602fn main() {
603 92;
604}
605```
606
607## `remove_hash`
608
609Removes a hash from a raw string literal.
610
611```rust
612// BEFORE
613fn main() {
614 r#"Hello,┃ World!"#;
615}
616
617// AFTER
618fn main() {
619 r"Hello, World!";
620}
621```
622
623## `remove_mut`
624
625Removes the `mut` keyword.
626
627```rust
628// BEFORE
629impl Walrus {
630 fn feed(&mut┃ self, amount: u32) {}
631}
632
633// AFTER
634impl Walrus {
635 fn feed(&self, amount: u32) {}
636}
637```
638
639## `reorder_fields`
640
641Reorder the fields of record literals and record patterns in the same order as in
642the definition.
643
644```rust
645// BEFORE
646struct Foo {foo: i32, bar: i32};
647const test: Foo = ┃Foo {bar: 0, foo: 1}
648
649// AFTER
650struct Foo {foo: i32, bar: i32};
651const test: Foo = Foo {foo: 1, bar: 0}
652```
653
654## `replace_if_let_with_match`
655
656Replaces `if let` with an else branch with a `match` expression.
657
658```rust
659// BEFORE
660enum Action { Move { distance: u32 }, Stop }
661
662fn handle(action: Action) {
663 ┃if let Action::Move { distance } = action {
664 foo(distance)
665 } else {
666 bar()
667 }
668}
669
670// AFTER
671enum Action { Move { distance: u32 }, Stop }
672
673fn handle(action: Action) {
674 match action {
675 Action::Move { distance } => foo(distance),
676 _ => bar(),
677 }
678}
679```
680
681## `replace_let_with_if_let`
682
683Replaces `let` with an `if-let`.
684
685```rust
686// BEFORE
687
688fn main(action: Action) {
689 ┃let x = compute();
690}
691
692fn compute() -> Option<i32> { None }
693
694// AFTER
695
696fn main(action: Action) {
697 if let Some(x) = compute() {
698 }
699}
700
701fn compute() -> Option<i32> { None }
702```
703
704## `replace_qualified_name_with_use`
705
706Adds a use statement for a given fully-qualified name.
707
708```rust
709// BEFORE
710fn process(map: std::collections::┃HashMap<String, String>) {}
711
712// AFTER
713use std::collections::HashMap;
714
715fn process(map: HashMap<String, String>) {}
716```
717
718## `replace_unwrap_with_match`
719
720Replaces `unwrap` a `match` expression. Works for Result and Option.
721
722```rust
723// BEFORE
724enum Result<T, E> { Ok(T), Err(E) }
725fn main() {
726 let x: Result<i32, i32> = Result::Ok(92);
727 let y = x.┃unwrap();
728}
729
730// AFTER
731enum Result<T, E> { Ok(T), Err(E) }
732fn main() {
733 let x: Result<i32, i32> = Result::Ok(92);
734 let y = match x {
735 Ok(a) => a,
736 $0_ => unreachable!(),
737 };
738}
739```
740
741## `split_import`
742
743Wraps the tail of import into braces.
744
745```rust
746// BEFORE
747use std::┃collections::HashMap;
748
749// AFTER
750use std::{collections::HashMap};
751```
752
753## `unwrap_block`
754
755This assist removes if...else, for, while and loop control statements to just keep the body.
756
757```rust
758// BEFORE
759fn foo() {
760 if true {┃
761 println!("foo");
762 }
763}
764
765// AFTER
766fn foo() {
767 println!("foo");
768}
769```
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/generated_assists.adoc b/docs/user/generated_assists.adoc
new file mode 100644
index 000000000..4d2fb31d4
--- /dev/null
+++ b/docs/user/generated_assists.adoc
@@ -0,0 +1,1015 @@
1[discrete]
2=== `add_custom_impl`
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
5Adds impl block for derived trait.
6
7.Before
8```rust
9#[derive(Deb┃ug, Display)]
10struct S;
11```
12
13.After
14```rust
15#[derive(Display)]
16struct S;
17
18impl Debug for S {
19 $0
20}
21```
22
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]
27
28Adds a new `#[derive()]` clause to a struct or enum.
29
30.Before
31```rust
32struct Point {
33 x: u32,
34 y: u32,┃
35}
36```
37
38.After
39```rust
40#[derive($0)]
41struct Point {
42 x: u32,
43 y: u32,
44}
45```
46
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]
51
52Specify type for a let binding.
53
54.Before
55```rust
56fn main() {
57 let x┃ = 92;
58}
59```
60
61.After
62```rust
63fn main() {
64 let x: i32 = 92;
65}
66```
67
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]
95
96Adds a stub function with a signature matching the function under the cursor.
97
98.Before
99```rust
100struct Baz;
101fn baz() -> Baz { Baz }
102fn foo() {
103 bar┃("", baz());
104}
105
106```
107
108.After
109```rust
110struct Baz;
111fn baz() -> Baz { Baz }
112fn foo() {
113 bar("", baz());
114}
115
116fn bar(arg: &str, baz: Baz) {
117 ${0:todo!()}
118}
119
120```
121
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]
126
127Adds a hash to a raw string literal.
128
129.Before
130```rust
131fn main() {
132 r#"Hello,┃ World!"#;
133}
134```
135
136.After
137```rust
138fn main() {
139 r##"Hello, World!"##;
140}
141```
142
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]
147
148Adds a new inherent impl for a type.
149
150.Before
151```rust
152struct Ctx<T: Clone> {
153 data: T,┃
154}
155```
156
157.After
158```rust
159struct Ctx<T: Clone> {
160 data: T,
161}
162
163impl<T: Clone> Ctx<T> {
164 $0
165}
166```
167
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]
172
173Adds scaffold for overriding default impl members.
174
175.Before
176```rust
177trait Trait {
178 Type X;
179 fn foo(&self);
180 fn bar(&self) {}
181}
182
183impl Trait for () {
184 Type X = ();
185 fn foo(&self) {}┃
186
187}
188```
189
190.After
191```rust
192trait Trait {
193 Type X;
194 fn foo(&self);
195 fn bar(&self) {}
196}
197
198impl Trait for () {
199 Type X = ();
200 fn foo(&self) {}
201 $0fn bar(&self) {}
202
203}
204```
205
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]
210
211Adds scaffold for required impl members.
212
213.Before
214```rust
215trait Trait<T> {
216 Type X;
217 fn foo(&self) -> T;
218 fn bar(&self) {}
219}
220
221impl Trait<u32> for () {┃
222
223}
224```
225
226.After
227```rust
228trait Trait<T> {
229 Type X;
230 fn foo(&self) -> T;
231 fn bar(&self) {}
232}
233
234impl Trait<u32> for () {
235 fn foo(&self) -> u32 {
236 ${0:todo!()}
237 }
238
239}
240```
241
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]
246
247Adds a new inherent impl for a type.
248
249.Before
250```rust
251struct Ctx<T: Clone> {
252 data: T,┃
253}
254```
255
256.After
257```rust
258struct Ctx<T: Clone> {
259 data: T,
260}
261
262impl<T: Clone> Ctx<T> {
263 fn $0new(data: T) -> Self { Self { data } }
264}
265
266```
267
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]
272
273Adds `::<_>` to a call of a generic method or function.
274
275.Before
276```rust
277fn make<T>() -> T { todo!() }
278fn main() {
279 let x = make┃();
280}
281```
282
283.After
284```rust
285fn make<T>() -> T { todo!() }
286fn main() {
287 let x = make::<${0:_}>();
288}
289```
290
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]
295
296Apply [De Morgan's law](https://en.wikipedia.org/wiki/De_Morgan%27s_laws).
297This transforms expressions of the form `!l || !r` into `!(l && r)`.
298This also works with `&&`. This assist can only be applied with the cursor
299on either `||` or `&&`, with both operands being a negation of some kind.
300This means something of the form `!x` or `x != y`.
301
302.Before
303```rust
304fn main() {
305 if x != 4 ||┃ !y {}
306}
307```
308
309.After
310```rust
311fn main() {
312 if !(x == 4 && y) {}
313}
314```
315
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]
320
321If the name is unresolved, provides all possible imports for it.
322
323.Before
324```rust
325fn main() {
326 let map = HashMap┃::new();
327}
328```
329
330.After
331```rust
332use std::collections::HashMap;
333
334fn main() {
335 let map = HashMap::new();
336}
337```
338
339
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]
343
344Change the function's return type to Result.
345
346.Before
347```rust
348fn foo() -> i32┃ { 42i32 }
349```
350
351.After
352```rust
353fn foo() -> Result<i32, ${0:_}> { Ok(42i32) }
354```
355
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]
360
361Adds or changes existing visibility specifier.
362
363.Before
364```rust
365┃fn frobnicate() {}
366```
367
368.After
369```rust
370pub(crate) fn frobnicate() {}
371```
372
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]
377
378Replace a large conditional with a guarded return.
379
380.Before
381```rust
382fn main() {
383 ┃if cond {
384 foo();
385 bar();
386 }
387}
388```
389
390.After
391```rust
392fn main() {
393 if !cond {
394 return;
395 }
396 foo();
397 bar();
398}
399```
400
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]
405
406Adds missing clauses to a `match` expression.
407
408.Before
409```rust
410enum Action { Move { distance: u32 }, Stop }
411
412fn handle(action: Action) {
413 match action {
414 ┃
415 }
416}
417```
418
419.After
420```rust
421enum Action { Move { distance: u32 }, Stop }
422
423fn handle(action: Action) {
424 match action {
425 $0Action::Move { distance } => {}
426 Action::Stop => {}
427 }
428}
429```
430
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]
435
436Makes inaccessible item public.
437
438.Before
439```rust
440mod m {
441 fn frobnicate() {}
442}
443fn main() {
444 m::frobnicate┃() {}
445}
446```
447
448.After
449```rust
450mod m {
451 $0pub(crate) fn frobnicate() {}
452}
453fn main() {
454 m::frobnicate() {}
455}
456```
457
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]
462
463Flips operands of a binary expression.
464
465.Before
466```rust
467fn main() {
468 let _ = 90 +┃ 2;
469}
470```
471
472.After
473```rust
474fn main() {
475 let _ = 2 + 90;
476}
477```
478
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]
483
484Flips two comma-separated items.
485
486.Before
487```rust
488fn main() {
489 ((1, 2),┃ (3, 4));
490}
491```
492
493.After
494```rust
495fn main() {
496 ((3, 4), (1, 2));
497}
498```
499
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]
504
505Flips two trait bounds.
506
507.Before
508```rust
509fn foo<T: Clone +┃ Copy>() { }
510```
511
512.After
513```rust
514fn foo<T: Copy + Clone>() { }
515```
516
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]
521
522Inlines local variable.
523
524.Before
525```rust
526fn main() {
527 let x┃ = 1 + 2;
528 x * 4;
529}
530```
531
532.After
533```rust
534fn main() {
535 (1 + 2) * 4;
536}
537```
538
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]
572
573Extracts subexpression into a variable.
574
575.Before
576```rust
577fn main() {
578 ┃(1 + 2)┃ * 4;
579}
580```
581
582.After
583```rust
584fn main() {
585 let $0var_name = (1 + 2);
586 var_name * 4;
587}
588```
589
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]
594
595Apply invert_if
596This transforms if expressions of the form `if !x {A} else {B}` into `if x {B} else {A}`
597This also works with `!=`. This assist can only be applied with the cursor
598on `if`.
599
600.Before
601```rust
602fn main() {
603 if┃ !y { A } else { B }
604}
605```
606
607.After
608```rust
609fn main() {
610 if y { B } else { A }
611}
612```
613
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]
618
619Adds `r#` to a plain string literal.
620
621.Before
622```rust
623fn main() {
624 "Hello,┃ World!";
625}
626```
627
628.After
629```rust
630fn main() {
631 r#"Hello, World!"#;
632}
633```
634
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]
639
640Turns a raw string into a plain string.
641
642.Before
643```rust
644fn main() {
645 r#"Hello,┃ "World!""#;
646}
647```
648
649.After
650```rust
651fn main() {
652 "Hello, \"World!\"";
653}
654```
655
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]
660
661Merges two imports with a common prefix.
662
663.Before
664```rust
665use std::┃fmt::Formatter;
666use std::io;
667```
668
669.After
670```rust
671use std::{fmt::Formatter, io};
672```
673
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]
678
679Merges identical match arms.
680
681.Before
682```rust
683enum Action { Move { distance: u32 }, Stop }
684
685fn handle(action: Action) {
686 match action {
687 ┃Action::Move(..) => foo(),
688 Action::Stop => foo(),
689 }
690}
691```
692
693.After
694```rust
695enum Action { Move { distance: u32 }, Stop }
696
697fn handle(action: Action) {
698 match action {
699 Action::Move(..) | Action::Stop => foo(),
700 }
701}
702```
703
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]
708
709Moves if expression from match arm body into a guard.
710
711.Before
712```rust
713enum Action { Move { distance: u32 }, Stop }
714
715fn handle(action: Action) {
716 match action {
717 Action::Move { distance } => ┃if distance > 10 { foo() },
718 _ => (),
719 }
720}
721```
722
723.After
724```rust
725enum Action { Move { distance: u32 }, Stop }
726
727fn handle(action: Action) {
728 match action {
729 Action::Move { distance } if distance > 10 => foo(),
730 _ => (),
731 }
732}
733```
734
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]
739
740Moves inline type bounds to a where clause.
741
742.Before
743```rust
744fn apply<T, U, ┃F: FnOnce(T) -> U>(f: F, x: T) -> U {
745 f(x)
746}
747```
748
749.After
750```rust
751fn apply<T, U, F>(f: F, x: T) -> U where F: FnOnce(T) -> U {
752 f(x)
753}
754```
755
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]
760
761Moves match guard into match arm body.
762
763.Before
764```rust
765enum Action { Move { distance: u32 }, Stop }
766
767fn handle(action: Action) {
768 match action {
769 Action::Move { distance } ┃if distance > 10 => foo(),
770 _ => (),
771 }
772}
773```
774
775.After
776```rust
777enum Action { Move { distance: u32 }, Stop }
778
779fn handle(action: Action) {
780 match action {
781 Action::Move { distance } => if distance > 10 { foo() },
782 _ => (),
783 }
784}
785```
786
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]
791
792Removes `dbg!()` macro call.
793
794.Before
795```rust
796fn main() {
797 ┃dbg!(92);
798}
799```
800
801.After
802```rust
803fn main() {
804 92;
805}
806```
807
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]
812
813Removes a hash from a raw string literal.
814
815.Before
816```rust
817fn main() {
818 r#"Hello,┃ World!"#;
819}
820```
821
822.After
823```rust
824fn main() {
825 r"Hello, World!";
826}
827```
828
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]
833
834Removes the `mut` keyword.
835
836.Before
837```rust
838impl Walrus {
839 fn feed(&mut┃ self, amount: u32) {}
840}
841```
842
843.After
844```rust
845impl Walrus {
846 fn feed(&self, amount: u32) {}
847}
848```
849
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]
854
855Reorder the fields of record literals and record patterns in the same order as in
856the definition.
857
858.Before
859```rust
860struct Foo {foo: i32, bar: i32};
861const test: Foo = ┃Foo {bar: 0, foo: 1}
862```
863
864.After
865```rust
866struct Foo {foo: i32, bar: i32};
867const test: Foo = Foo {foo: 1, bar: 0}
868```
869
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]
874
875Replaces `if let` with an else branch with a `match` expression.
876
877.Before
878```rust
879enum Action { Move { distance: u32 }, Stop }
880
881fn handle(action: Action) {
882 ┃if let Action::Move { distance } = action {
883 foo(distance)
884 } else {
885 bar()
886 }
887}
888```
889
890.After
891```rust
892enum Action { Move { distance: u32 }, Stop }
893
894fn handle(action: Action) {
895 match action {
896 Action::Move { distance } => foo(distance),
897 _ => bar(),
898 }
899}
900```
901
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]
906
907Replaces `let` with an `if-let`.
908
909.Before
910```rust
911
912fn main(action: Action) {
913 ┃let x = compute();
914}
915
916fn compute() -> Option<i32> { None }
917```
918
919.After
920```rust
921
922fn main(action: Action) {
923 if let Some(x) = compute() {
924 }
925}
926
927fn compute() -> Option<i32> { None }
928```
929
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]
934
935Adds a use statement for a given fully-qualified name.
936
937.Before
938```rust
939fn process(map: std::collections::┃HashMap<String, String>) {}
940```
941
942.After
943```rust
944use std::collections::HashMap;
945
946fn process(map: HashMap<String, String>) {}
947```
948
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]
953
954Replaces `unwrap` a `match` expression. Works for Result and Option.
955
956.Before
957```rust
958enum Result<T, E> { Ok(T), Err(E) }
959fn main() {
960 let x: Result<i32, i32> = Result::Ok(92);
961 let y = x.┃unwrap();
962}
963```
964
965.After
966```rust
967enum Result<T, E> { Ok(T), Err(E) }
968fn main() {
969 let x: Result<i32, i32> = Result::Ok(92);
970 let y = match x {
971 Ok(a) => a,
972 $0_ => unreachable!(),
973 };
974}
975```
976
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]
981
982Wraps the tail of import into braces.
983
984.Before
985```rust
986use std::┃collections::HashMap;
987```
988
989.After
990```rust
991use std::{collections::HashMap};
992```
993
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]
998
999This assist removes if...else, for, while and loop control statements to just keep the body.
1000
1001.Before
1002```rust
1003fn foo() {
1004 if true {┃
1005 println!("foo");
1006 }
1007}
1008```
1009
1010.After
1011```rust
1012fn foo() {
1013 println!("foo");
1014}
1015```
diff --git a/docs/user/generated_features.adoc b/docs/user/generated_features.adoc
new file mode 100644
index 000000000..4b93b759f
--- /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#L58[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-09-29 09:29:32 +0100