diff options
Diffstat (limited to 'docs/user/features.md')
-rw-r--r-- | docs/user/features.md | 218 |
1 files changed, 0 insertions, 218 deletions
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 @@ | |||
1 | This document is an index of features that the rust-analyzer language server | ||
2 | provides. Shortcuts are for the default VS Code layout. If there's no shortcut, | ||
3 | you can use <kbd>Ctrl+Shift+P</kbd> to search for the corresponding action. | ||
4 | |||
5 | ### Workspace Symbol <kbd>ctrl+t</kbd> | ||
6 | |||
7 | Uses fuzzy-search to find types, modules and functions by name across your | ||
8 | project and dependencies. This is **the** most useful feature, which improves code | ||
9 | navigation tremendously. It mostly works on top of the built-in LSP | ||
10 | functionality, however `#` and `*` symbols can be used to narrow down the | ||
11 | search. 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 | |||
18 | That is, `#` switches from "types" to all symbols, `*` switches from the current | ||
19 | workspace to dependencies. | ||
20 | |||
21 | ### Document Symbol <kbd>ctrl+shift+o</kbd> | ||
22 | |||
23 | Provides 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 | |||
31 | Some 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 | |||
39 | Extends the current selection to the encompassing syntactic construct | ||
40 | (expression, statement, item, module, etc). It works with multiple cursors. This | ||
41 | is a relatively new feature of LSP: | ||
42 | https://github.com/Microsoft/language-server-protocol/issues/613, check your | ||
43 | editor's LSP library to see if this feature is supported. | ||
44 | |||
45 | ### Go to Definition | ||
46 | |||
47 | Navigates to the definition of an identifier. | ||
48 | |||
49 | ### Go to Implementation | ||
50 | |||
51 | Navigates to the impl block of structs, enums or traits. Also implemented as a code lens. | ||
52 | |||
53 | ### Go to Type Defintion | ||
54 | |||
55 | Navigates to the type of an identifier. | ||
56 | |||
57 | ### Commands <kbd>ctrl+shift+p</kbd> | ||
58 | |||
59 | #### Run | ||
60 | |||
61 | Shows a popup suggesting to run a test/benchmark/binary **at the current cursor | ||
62 | location**. Super useful for repeatedly running just a single test. Do bind this | ||
63 | to a shortcut! | ||
64 | |||
65 | #### Parent Module | ||
66 | |||
67 | Navigates to the parent module of the current module. | ||
68 | |||
69 | #### Matching Brace | ||
70 | |||
71 | If the cursor is on any brace (`<>(){}[]`) which is a part of a brace-pair, | ||
72 | moves cursor to the matching brace. It uses the actual parser to determine | ||
73 | braces, so it won't confuse generics with comparisons. | ||
74 | |||
75 | #### Join Lines | ||
76 | |||
77 | Join selected lines into one, smartly fixing up whitespace and trailing commas. | ||
78 | |||
79 | #### Show Syntax Tree | ||
80 | |||
81 | Shows the parse tree of the current file. It exists mostly for debugging | ||
82 | rust-analyzer itself. | ||
83 | |||
84 | #### Expand Macro Recursively | ||
85 | |||
86 | Shows the full macro expansion of the macro at current cursor. | ||
87 | |||
88 | #### Status | ||
89 | |||
90 | Shows internal statistic about memory usage of rust-analyzer. | ||
91 | |||
92 | #### Show RA Version | ||
93 | |||
94 | Show current rust-analyzer version. | ||
95 | |||
96 | #### Toggle inlay hints | ||
97 | |||
98 | Toggle inlay hints view for the current workspace. | ||
99 | It is recommended to assign a shortcut for this command to quickly turn off | ||
100 | inlay hints when they prevent you from reading/writing the code. | ||
101 | |||
102 | #### Run Garbage Collection | ||
103 | |||
104 | Manually triggers GC. | ||
105 | |||
106 | #### Start Cargo Watch | ||
107 | |||
108 | Start `cargo watch` for live error highlighting. Will prompt to install if it's not already installed. | ||
109 | |||
110 | #### Stop Cargo Watch | ||
111 | |||
112 | Stop `cargo watch`. | ||
113 | |||
114 | #### Structural Seach and Replace | ||
115 | |||
116 | Search and replace with named wildcards that will match any expression. | ||
117 | The 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 | ||
123 | String::from(foo(y + 5, z)) | ||
124 | |||
125 | // AFTER | ||
126 | String::from((y + 5).foo(z)) | ||
127 | ``` | ||
128 | |||
129 | ### Assists (Code Actions) | ||
130 | |||
131 | Assists, or code actions, are small local refactorings, available in a particular context. | ||
132 | They are usually triggered by a shortcut or by clicking a light bulb icon in the editor. | ||
133 | |||
134 | See [assists.md](./assists.md) for the list of available assists. | ||
135 | |||
136 | ### Magic Completions | ||
137 | |||
138 | In addition to usual reference completion, rust-analyzer provides some ✨magic✨ | ||
139 | completions as well: | ||
140 | |||
141 | Keywords like `if`, `else` `while`, `loop` are completed with braces, and cursor | ||
142 | is placed at the appropriate position. Even though `if` is easy to type, you | ||
143 | still want to complete it, to get ` { }` for free! `return` is inserted with a | ||
144 | space or `;` depending on the return type of the function. | ||
145 | |||
146 | When completing a function call, `()` are automatically inserted. If a function | ||
147 | takes arguments, the cursor is positioned inside the parenthesis. | ||
148 | |||
149 | There 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 | |||
160 | There 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)] | ||
173 | mod tests { | ||
174 | use super::*; | ||
175 | |||
176 | #[test] | ||
177 | fn test_fn() {} | ||
178 | } | ||
179 | ``` | ||
180 | |||
181 | ### Code Highlighting | ||
182 | |||
183 | Experimental feature to let rust-analyzer highlight Rust code instead of using the | ||
184 | default highlighter. | ||
185 | |||
186 | #### Rainbow Highlighting | ||
187 | |||
188 | Experimental feature that, given code highlighting using rust-analyzer is | ||
189 | active, will pick unique colors for identifiers. | ||
190 | |||
191 | ### Code hints | ||
192 | |||
193 | Rust-analyzer has two types of hints to show the information about the code: | ||
194 | |||
195 | * hover hints, appearing on hover on any element. | ||
196 | |||
197 | These contain extended information on the hovered language item. | ||
198 | |||
199 | * inlay hints, shown near the element hinted directly in the editor. | ||
200 | |||
201 | Two 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 | |||
209 | In 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. | ||
217 | This 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). | ||