aboutsummaryrefslogtreecommitdiff
path: root/docs
diff options
context:
space:
mode:
authorAleksey Kladov <[email protected]>2020-05-31 10:29:19 +0100
committerAleksey Kladov <[email protected]>2020-05-31 10:29:19 +0100
commit1c6a2eb14a84c3a66972d1a6da429cca1aa8b40a (patch)
treeadc80cc0840911ca3aa86fd03fff6e49d99cc821 /docs
parentb795a07320e13bcbedb6435bcfddb3ecd0ed2bde (diff)
Move the rest of the features to generated docs
Diffstat (limited to 'docs')
-rw-r--r--docs/user/features.md96
-rw-r--r--docs/user/generated_features.adoc143
-rw-r--r--docs/user/readme.adoc1
3 files changed, 144 insertions, 96 deletions
diff --git a/docs/user/features.md b/docs/user/features.md
deleted file mode 100644
index ff8cb2d6e..000000000
--- a/docs/user/features.md
+++ /dev/null
@@ -1,96 +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### Commands <kbd>ctrl+shift+p</kbd>
6
7
8#### Toggle inlay hints
9
10Toggle inlay hints view for the current workspace.
11It is recommended to assign a shortcut for this command to quickly turn off
12inlay hints when they prevent you from reading/writing the code.
13
14### Magic Completions
15
16In addition to usual reference completion, rust-analyzer provides some ✨magic✨
17completions as well:
18
19Keywords like `if`, `else` `while`, `loop` are completed with braces, and cursor
20is placed at the appropriate position. Even though `if` is easy to type, you
21still want to complete it, to get ` { }` for free! `return` is inserted with a
22space or `;` depending on the return type of the function.
23
24When completing a function call, `()` are automatically inserted. If a function
25takes arguments, the cursor is positioned inside the parenthesis.
26
27There are postfix completions, which can be triggered by typing something like
28`foo().if`. The word after `.` determines postfix completion. Possible variants are:
29
30- `expr.if` -> `if expr {}` or `if let ... {}` for `Option` or `Result`
31- `expr.match` -> `match expr {}`
32- `expr.while` -> `while expr {}` or `while let ... {}` for `Option` or `Result`
33- `expr.ref` -> `&expr`
34- `expr.refm` -> `&mut expr`
35- `expr.not` -> `!expr`
36- `expr.dbg` -> `dbg!(expr)`
37
38There also snippet completions:
39
40#### Inside Expressions
41
42- `pd` -> `println!("{:?}")`
43- `ppd` -> `println!("{:#?}")`
44
45#### Inside Modules
46
47- `tfn` -> `#[test] fn f(){}`
48- `tmod` ->
49```rust
50#[cfg(test)]
51mod tests {
52 use super::*;
53
54 #[test]
55 fn test_fn() {}
56}
57```
58
59### Code Highlighting
60
61Experimental feature to let rust-analyzer highlight Rust code instead of using the
62default highlighter.
63
64#### Rainbow Highlighting
65
66Experimental feature that, given code highlighting using rust-analyzer is
67active, will pick unique colors for identifiers.
68
69### Code hints
70
71Rust-analyzer has two types of hints to show the information about the code:
72
73* hover hints, appearing on hover on any element.
74
75These contain extended information on the hovered language item.
76
77* inlay hints, shown near the element hinted directly in the editor.
78
79Two types of inlay hints are displayed currently:
80
81* type hints, displaying the minimal information on the type of the expression (if the information is available)
82* method chaining hints, type information for multi-line method chains
83* parameter name hints, displaying the names of the parameters in the corresponding methods
84
85#### VS Code
86
87In VS Code, the following settings can be used to configure the inlay hints:
88
89* `rust-analyzer.inlayHints.typeHints` - enable hints for inferred types.
90* `rust-analyzer.inlayHints.chainingHints` - enable hints for inferred types on method chains.
91* `rust-analyzer.inlayHints.parameterHints` - enable hints for function parameters.
92* `rust-analyzer.inlayHints.maxLength` — shortens the hints if their length exceeds the value specified. If no value is specified (`null`), no shortening is applied.
93
94**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.
95This approach has limitations, the caret movement and bracket highlighting near the edges of the hint may be weird:
96[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_features.adoc b/docs/user/generated_features.adoc
index bf0a36d01..a806e3ff1 100644
--- a/docs/user/generated_features.adoc
+++ b/docs/user/generated_features.adoc
@@ -1,3 +1,16 @@
1=== Expand Macro Recursively
2**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_ide/src/expand_macro.rs[expand_macro.rs]
3
4
5Shows the full macro expansion of the macro at current cursor.
6
7|===
8| Editor | Action Name
9
10| VS Code | **Rust Analyzer: Expand macro recursively**
11|===
12
13
1=== Extend Selection 14=== Extend Selection
2**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_ide/src/extend_selection.rs[extend_selection.rs] 15**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_ide/src/extend_selection.rs[extend_selection.rs]
3 16
@@ -68,6 +81,38 @@ Navigates to the type of an identifier.
68|=== 81|===
69 82
70 83
84=== Hover
85**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_ide/src/hover.rs[hover.rs]
86
87
88Shows additional information, like type of an expression or documentation for definition when "focusing" code.
89Focusing is usually hovering with a mouse, but can also be triggered with a shortcut.
90
91
92=== Inlay Hints
93**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_ide/src/inlay_hints.rs[inlay_hints.rs]
94
95
96rust-analyzer shows additional information inline with the source code.
97Editors usually render this using read-only virtual text snippets interspersed with code.
98
99rust-analyzer shows hits for
100
101* types of local variables
102* names of function arguments
103* types of chained expressions
104
105**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.
106This approach has limitations, the caret movement and bracket highlighting near the edges of the hint may be weird:
107https://github.com/rust-analyzer/rust-analyzer/issues/1623[1], https://github.com/rust-analyzer/rust-analyzer/issues/3453[2].
108
109|===
110| Editor | Action Name
111
112| VS Code | **Rust Analyzer: Toggle inlay hints*
113|===
114
115
71=== Join Lines 116=== Join Lines
72**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_ide/src/join_lines.rs[join_lines.rs] 117**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_ide/src/join_lines.rs[join_lines.rs]
73 118
@@ -81,6 +126,52 @@ Join selected lines into one, smartly fixing up whitespace, trailing commas, and
81|=== 126|===
82 127
83 128
129=== Magic Completions
130**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_ide/src/completion.rs[completion.rs]
131
132
133In addition to usual reference completion, rust-analyzer provides some ✨magic✨
134completions as well:
135
136Keywords like `if`, `else` `while`, `loop` are completed with braces, and cursor
137is placed at the appropriate position. Even though `if` is easy to type, you
138still want to complete it, to get ` { }` for free! `return` is inserted with a
139space or `;` depending on the return type of the function.
140
141When completing a function call, `()` are automatically inserted. If a function
142takes arguments, the cursor is positioned inside the parenthesis.
143
144There are postfix completions, which can be triggered by typing something like
145`foo().if`. The word after `.` determines postfix completion. Possible variants are:
146
147- `expr.if` -> `if expr {}` or `if let ... {}` for `Option` or `Result`
148- `expr.match` -> `match expr {}`
149- `expr.while` -> `while expr {}` or `while let ... {}` for `Option` or `Result`
150- `expr.ref` -> `&expr`
151- `expr.refm` -> `&mut expr`
152- `expr.not` -> `!expr`
153- `expr.dbg` -> `dbg!(expr)`
154
155There also snippet completions:
156
157.Expressions
158- `pd` -> `println!("{:?}")`
159- `ppd` -> `println!("{:#?}")`
160
161.Items
162- `tfn` -> `#[test] fn f(){}`
163- `tmod` ->
164```rust
165#[cfg(test)]
166mod tests {
167 use super::*;
168
169 #[test]
170 fn test_fn() {}
171}
172```
173
174
84=== Matching Brace 175=== Matching Brace
85**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_ide/src/matching_brace.rs[matching_brace.rs] 176**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_ide/src/matching_brace.rs[matching_brace.rs]
86 177
@@ -135,6 +226,19 @@ to a shortcut!
135|=== 226|===
136 227
137 228
229=== Semantic Syntax Highlighting
230**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_ide/src/syntax_highlighting.rs[syntax_highlighting.rs]
231
232
233rust-analyzer highlights the code semantically.
234For example, `bar` in `foo::Bar` might be colored differently depending on whether `Bar` is an enum or a trait.
235rust-analyzer does not specify colors directly, instead it assigns tag (like `struct`) and a set of modifiers (like `declaration`) to each token.
236It's up to the client to map those to specific colors.
237
238The general rule is that a reference to an entity gets colored the same way as the entity itself.
239We also give special modifier for `mut` and `&mut` local variables.
240
241
138=== Show Syntax Tree 242=== Show Syntax Tree
139**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_ide/src/syntax_tree.rs[syntax_tree.rs] 243**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_ide/src/syntax_tree.rs[syntax_tree.rs]
140 244
@@ -149,6 +253,45 @@ rust-analyzer itself.
149|=== 253|===
150 254
151 255
256=== Status
257**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_ide/src/status.rs[status.rs]
258
259
260Shows internal statistic about memory usage of rust-analyzer.
261
262|===
263| Editor | Action Name
264
265| VS Code | **Rust Analyzer: Status**
266|===
267
268
269=== Structural Seach and Replace
270**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_ide/src/ssr.rs[ssr.rs]
271
272
273Search and replace with named wildcards that will match any expression.
274The syntax for a structural search replace command is `<search_pattern> ==>> <replace_pattern>`.
275A `$<name>:expr` placeholder in the search pattern will match any expression and `$<name>` will reference it in the replacement.
276Available via the command `rust-analyzer.ssr`.
277
278```rust
279// Using structural search replace command [foo($a:expr, $b:expr) ==>> ($a).foo($b)]
280
281// BEFORE
282String::from(foo(y + 5, z))
283
284// AFTER
285String::from((y + 5).foo(z))
286```
287
288|===
289| Editor | Action Name
290
291| VS Code | **Rust Analyzer: Structural Search Replace**
292|===
293
294
152=== Workspace Symbol 295=== Workspace Symbol
153**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_ide_db/src/symbol_index.rs[symbol_index.rs] 296**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_ide_db/src/symbol_index.rs[symbol_index.rs]
154 297
diff --git a/docs/user/readme.adoc b/docs/user/readme.adoc
index 8cfa41144..12def7327 100644
--- a/docs/user/readme.adoc
+++ b/docs/user/readme.adoc
@@ -8,6 +8,7 @@
8:important-caption: :heavy_exclamation_mark: 8:important-caption: :heavy_exclamation_mark:
9:caution-caption: :fire: 9:caution-caption: :fire:
10:warning-caption: :warning: 10:warning-caption: :warning:
11:source-highlighter: rouge
11:experimental: 12:experimental:
12 13
13// Master copy of this document lives in the https://github.com/rust-analyzer/rust-analyzer repository 14// Master copy of this document lives in the https://github.com/rust-analyzer/rust-analyzer repository