From c8f27a4a886413a15a2a6af4a87b39b901c873a8 Mon Sep 17 00:00:00 2001 From: Aleksey Kladov Date: Sun, 31 May 2020 01:54:54 +0200 Subject: Generate features docs from source --- docs/user/generated_features.adoc | 98 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 98 insertions(+) create mode 100644 docs/user/generated_features.adoc (limited to 'docs/user/generated_features.adoc') diff --git a/docs/user/generated_features.adoc b/docs/user/generated_features.adoc new file mode 100644 index 000000000..e1eb5d88a --- /dev/null +++ b/docs/user/generated_features.adoc @@ -0,0 +1,98 @@ +=== Extend Selection +**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_ide/src/extend_selection.rs[extend_selection.rs] + + +Extends the current selection to the encompassing syntactic construct +(expression, statement, item, module, etc). It works with multiple cursors. + +|=== +| Editor | Shortcut + +| VS Code | kbd:[Ctrl+Shift+→] +|=== + + +=== File Structure +**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_ide/src/display/structure.rs[structure.rs] + + +Provides a tree of the symbols defined in the file. Can be used to + +* fuzzy search symbol in a file (super useful) +* draw breadcrumbs to describe the context around the cursor +* draw outline of the file + +|=== +| Editor | Shortcut + +| VS Code | kbd:[Ctrl+Shift+O] +|=== + + +=== Go To Definition +**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_ide/src/goto_definition.rs[goto_definition.rs] + + +Navigates to the definition of an identifier. + +|=== +| Editor | Shortcut + +| VS Code | kbd:[F12] +|=== + + +=== Go To Implementation +**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_ide/src/goto_implementation.rs[goto_implementation.rs] + + +Navigates to the impl block of structs, enums or traits. Also implemented as a code lens. + +|=== +| Editor | Shortcut + +| VS Code | kbd:[Ctrl+F12] +|=== + + +=== Go To Type Definition +**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_ide/src/goto_type_definition.rs[goto_type_definition.rs] + + +Navigates to the type of an identifier. + + +=== On Typing Assists +**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_ide/src/typing.rs[typing.rs] + + +Some features trigger on typing certain characters: + +- typing `let =` tries to smartly add `;` if `=` is followed by an existing expression +- Enter inside comments automatically inserts `///` +- typing `.` in a chain method call auto-indents + + +=== Workspace Symbol +**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_ide_db/src/symbol_index.rs[symbol_index.rs] + + +Uses fuzzy-search to find types, modules and functions by name across your +project and dependencies. This is **the** most useful feature, which improves code +navigation tremendously. It mostly works on top of the built-in LSP +functionality, however `#` and `*` symbols can be used to narrow down the +search. Specifically, + +- `Foo` searches for `Foo` type in the current workspace +- `foo#` searches for `foo` function in the current workspace +- `Foo*` searches for `Foo` type among dependencies, including `stdlib` +- `foo#*` searches for `foo` function among dependencies + +That is, `#` switches from "types" to all symbols, `*` switches from the current +workspace to dependencies. + +|=== +| Editor | Shortcut + +| VS Code | kbd:[Ctrl+T] +|=== -- cgit v1.2.3 From f593393ebb9bfa515caf168a9f037324eeb6edfe Mon Sep 17 00:00:00 2001 From: Aleksey Kladov Date: Sun, 31 May 2020 09:45:41 +0200 Subject: Specify actions --- docs/user/generated_features.adoc | 27 ++++++++++++++++++++++++--- 1 file changed, 24 insertions(+), 3 deletions(-) (limited to 'docs/user/generated_features.adoc') diff --git a/docs/user/generated_features.adoc b/docs/user/generated_features.adoc index e1eb5d88a..1f6fcc974 100644 --- a/docs/user/generated_features.adoc +++ b/docs/user/generated_features.adoc @@ -29,7 +29,7 @@ Provides a tree of the symbols defined in the file. Can be used to |=== -=== Go To Definition +=== Go to Definition **Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_ide/src/goto_definition.rs[goto_definition.rs] @@ -42,7 +42,7 @@ Navigates to the definition of an identifier. |=== -=== Go To Implementation +=== Go to Implementation **Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_ide/src/goto_implementation.rs[goto_implementation.rs] @@ -55,12 +55,18 @@ Navigates to the impl block of structs, enums or traits. Also implemented as a c |=== -=== Go To Type Definition +=== Go to Type Definition **Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_ide/src/goto_type_definition.rs[goto_type_definition.rs] Navigates to the type of an identifier. +|=== +| Editor | Action Name + +| VS Code | **Go to Type Definition* +|=== + === On Typing Assists **Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_ide/src/typing.rs[typing.rs] @@ -73,6 +79,21 @@ Some features trigger on typing certain characters: - typing `.` in a chain method call auto-indents +=== Run +**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_ide/src/runnables.rs[runnables.rs] + + +Shows a popup suggesting to run a test/benchmark/binary **at the current cursor +location**. Super useful for repeatedly running just a single test. Do bind this +to a shortcut! + +|=== +| Editor | Action Name + +| VS Code | **Rust Analyzer: Run** +|=== + + === Workspace Symbol **Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_ide_db/src/symbol_index.rs[symbol_index.rs] -- cgit v1.2.3 From 8915183d7da07a4b295e5e93a889dea4c15024a0 Mon Sep 17 00:00:00 2001 From: Aleksey Kladov Date: Sun, 31 May 2020 09:59:38 +0200 Subject: Don't require module docs for Features and Assists --- docs/user/generated_features.adoc | 55 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 55 insertions(+) (limited to 'docs/user/generated_features.adoc') diff --git a/docs/user/generated_features.adoc b/docs/user/generated_features.adoc index 1f6fcc974..bf0a36d01 100644 --- a/docs/user/generated_features.adoc +++ b/docs/user/generated_features.adoc @@ -68,6 +68,34 @@ Navigates to the type of an identifier. |=== +=== Join Lines +**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_ide/src/join_lines.rs[join_lines.rs] + + +Join selected lines into one, smartly fixing up whitespace, trailing commas, and braces. + +|=== +| Editor | Action Name + +| VS Code | **Rust Analyzer: Join lines** +|=== + + +=== Matching Brace +**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_ide/src/matching_brace.rs[matching_brace.rs] + + +If the cursor is on any brace (`<>(){}[]`) which is a part of a brace-pair, +moves cursor to the matching brace. It uses the actual parser to determine +braces, so it won't confuse generics with comparisons. + +|=== +| Editor | Action Name + +| VS Code | **Rust Analyzer: Find matching brace** +|=== + + === On Typing Assists **Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_ide/src/typing.rs[typing.rs] @@ -79,6 +107,19 @@ Some features trigger on typing certain characters: - typing `.` in a chain method call auto-indents +=== Parent Module +**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_ide/src/parent_module.rs[parent_module.rs] + + +Navigates to the parent module of the current module. + +|=== +| Editor | Action Name + +| VS Code | **Rust Analyzer: Locate parent module** +|=== + + === Run **Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_ide/src/runnables.rs[runnables.rs] @@ -94,6 +135,20 @@ to a shortcut! |=== +=== Show Syntax Tree +**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_ide/src/syntax_tree.rs[syntax_tree.rs] + + +Shows the parse tree of the current file. It exists mostly for debugging +rust-analyzer itself. + +|=== +| Editor | Action Name + +| VS Code | **Rust Analyzer: Show Syntax Tree** +|=== + + === Workspace Symbol **Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_ide_db/src/symbol_index.rs[symbol_index.rs] -- cgit v1.2.3 From 1c6a2eb14a84c3a66972d1a6da429cca1aa8b40a Mon Sep 17 00:00:00 2001 From: Aleksey Kladov Date: Sun, 31 May 2020 11:29:19 +0200 Subject: Move the rest of the features to generated docs --- docs/user/generated_features.adoc | 143 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 143 insertions(+) (limited to 'docs/user/generated_features.adoc') 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 @@ +=== Expand Macro Recursively +**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_ide/src/expand_macro.rs[expand_macro.rs] + + +Shows the full macro expansion of the macro at current cursor. + +|=== +| Editor | Action Name + +| VS Code | **Rust Analyzer: Expand macro recursively** +|=== + + === Extend Selection **Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_ide/src/extend_selection.rs[extend_selection.rs] @@ -68,6 +81,38 @@ Navigates to the type of an identifier. |=== +=== Hover +**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_ide/src/hover.rs[hover.rs] + + +Shows additional information, like type of an expression or documentation for definition when "focusing" code. +Focusing is usually hovering with a mouse, but can also be triggered with a shortcut. + + +=== Inlay Hints +**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_ide/src/inlay_hints.rs[inlay_hints.rs] + + +rust-analyzer shows additional information inline with the source code. +Editors usually render this using read-only virtual text snippets interspersed with code. + +rust-analyzer shows hits for + +* types of local variables +* names of function arguments +* types of chained expressions + +**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. +This approach has limitations, the caret movement and bracket highlighting near the edges of the hint may be weird: +https://github.com/rust-analyzer/rust-analyzer/issues/1623[1], https://github.com/rust-analyzer/rust-analyzer/issues/3453[2]. + +|=== +| Editor | Action Name + +| VS Code | **Rust Analyzer: Toggle inlay hints* +|=== + + === Join Lines **Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_ide/src/join_lines.rs[join_lines.rs] @@ -81,6 +126,52 @@ Join selected lines into one, smartly fixing up whitespace, trailing commas, and |=== +=== Magic Completions +**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_ide/src/completion.rs[completion.rs] + + +In addition to usual reference completion, rust-analyzer provides some ✨magic✨ +completions as well: + +Keywords like `if`, `else` `while`, `loop` are completed with braces, and cursor +is placed at the appropriate position. Even though `if` is easy to type, you +still want to complete it, to get ` { }` for free! `return` is inserted with a +space or `;` depending on the return type of the function. + +When completing a function call, `()` are automatically inserted. If a function +takes arguments, the cursor is positioned inside the parenthesis. + +There are postfix completions, which can be triggered by typing something like +`foo().if`. The word after `.` determines postfix completion. Possible variants are: + +- `expr.if` -> `if expr {}` or `if let ... {}` for `Option` or `Result` +- `expr.match` -> `match expr {}` +- `expr.while` -> `while expr {}` or `while let ... {}` for `Option` or `Result` +- `expr.ref` -> `&expr` +- `expr.refm` -> `&mut expr` +- `expr.not` -> `!expr` +- `expr.dbg` -> `dbg!(expr)` + +There also snippet completions: + +.Expressions +- `pd` -> `println!("{:?}")` +- `ppd` -> `println!("{:#?}")` + +.Items +- `tfn` -> `#[test] fn f(){}` +- `tmod` -> +```rust +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn test_fn() {} +} +``` + + === Matching Brace **Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_ide/src/matching_brace.rs[matching_brace.rs] @@ -135,6 +226,19 @@ to a shortcut! |=== +=== Semantic Syntax Highlighting +**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_ide/src/syntax_highlighting.rs[syntax_highlighting.rs] + + +rust-analyzer highlights the code semantically. +For example, `bar` in `foo::Bar` might be colored differently depending on whether `Bar` is an enum or a trait. +rust-analyzer does not specify colors directly, instead it assigns tag (like `struct`) and a set of modifiers (like `declaration`) to each token. +It's up to the client to map those to specific colors. + +The general rule is that a reference to an entity gets colored the same way as the entity itself. +We also give special modifier for `mut` and `&mut` local variables. + + === Show Syntax Tree **Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_ide/src/syntax_tree.rs[syntax_tree.rs] @@ -149,6 +253,45 @@ rust-analyzer itself. |=== +=== Status +**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_ide/src/status.rs[status.rs] + + +Shows internal statistic about memory usage of rust-analyzer. + +|=== +| Editor | Action Name + +| VS Code | **Rust Analyzer: Status** +|=== + + +=== Structural Seach and Replace +**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_ide/src/ssr.rs[ssr.rs] + + +Search and replace with named wildcards that will match any expression. +The syntax for a structural search replace command is ` ==>> `. +A `$:expr` placeholder in the search pattern will match any expression and `$` will reference it in the replacement. +Available via the command `rust-analyzer.ssr`. + +```rust +// Using structural search replace command [foo($a:expr, $b:expr) ==>> ($a).foo($b)] + +// BEFORE +String::from(foo(y + 5, z)) + +// AFTER +String::from((y + 5).foo(z)) +``` + +|=== +| Editor | Action Name + +| VS Code | **Rust Analyzer: Structural Search Replace** +|=== + + === Workspace Symbol **Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_ide_db/src/symbol_index.rs[symbol_index.rs] -- cgit v1.2.3 From 7e3ee77c83dc4e9af470491046206bf46d2a9a7e Mon Sep 17 00:00:00 2001 From: Aleksey Kladov Date: Sun, 31 May 2020 12:12:41 +0200 Subject: Tweak whitespace --- docs/user/generated_features.adoc | 19 ------------------- 1 file changed, 19 deletions(-) (limited to 'docs/user/generated_features.adoc') diff --git a/docs/user/generated_features.adoc b/docs/user/generated_features.adoc index a806e3ff1..803073d55 100644 --- a/docs/user/generated_features.adoc +++ b/docs/user/generated_features.adoc @@ -1,7 +1,6 @@ === Expand Macro Recursively **Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_ide/src/expand_macro.rs[expand_macro.rs] - Shows the full macro expansion of the macro at current cursor. |=== @@ -14,7 +13,6 @@ Shows the full macro expansion of the macro at current cursor. === Extend Selection **Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_ide/src/extend_selection.rs[extend_selection.rs] - Extends the current selection to the encompassing syntactic construct (expression, statement, item, module, etc). It works with multiple cursors. @@ -28,7 +26,6 @@ Extends the current selection to the encompassing syntactic construct === File Structure **Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_ide/src/display/structure.rs[structure.rs] - Provides a tree of the symbols defined in the file. Can be used to * fuzzy search symbol in a file (super useful) @@ -45,7 +42,6 @@ Provides a tree of the symbols defined in the file. Can be used to === Go to Definition **Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_ide/src/goto_definition.rs[goto_definition.rs] - Navigates to the definition of an identifier. |=== @@ -58,7 +54,6 @@ Navigates to the definition of an identifier. === Go to Implementation **Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_ide/src/goto_implementation.rs[goto_implementation.rs] - Navigates to the impl block of structs, enums or traits. Also implemented as a code lens. |=== @@ -71,7 +66,6 @@ Navigates to the impl block of structs, enums or traits. Also implemented as a c === Go to Type Definition **Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_ide/src/goto_type_definition.rs[goto_type_definition.rs] - Navigates to the type of an identifier. |=== @@ -84,7 +78,6 @@ Navigates to the type of an identifier. === Hover **Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_ide/src/hover.rs[hover.rs] - Shows additional information, like type of an expression or documentation for definition when "focusing" code. Focusing is usually hovering with a mouse, but can also be triggered with a shortcut. @@ -92,7 +85,6 @@ Focusing is usually hovering with a mouse, but can also be triggered with a shor === Inlay Hints **Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_ide/src/inlay_hints.rs[inlay_hints.rs] - rust-analyzer shows additional information inline with the source code. Editors usually render this using read-only virtual text snippets interspersed with code. @@ -116,7 +108,6 @@ https://github.com/rust-analyzer/rust-analyzer/issues/1623[1], https://github.co === Join Lines **Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_ide/src/join_lines.rs[join_lines.rs] - Join selected lines into one, smartly fixing up whitespace, trailing commas, and braces. |=== @@ -129,7 +120,6 @@ Join selected lines into one, smartly fixing up whitespace, trailing commas, and === Magic Completions **Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_ide/src/completion.rs[completion.rs] - In addition to usual reference completion, rust-analyzer provides some ✨magic✨ completions as well: @@ -175,7 +165,6 @@ mod tests { === Matching Brace **Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_ide/src/matching_brace.rs[matching_brace.rs] - If the cursor is on any brace (`<>(){}[]`) which is a part of a brace-pair, moves cursor to the matching brace. It uses the actual parser to determine braces, so it won't confuse generics with comparisons. @@ -190,7 +179,6 @@ braces, so it won't confuse generics with comparisons. === On Typing Assists **Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_ide/src/typing.rs[typing.rs] - Some features trigger on typing certain characters: - typing `let =` tries to smartly add `;` if `=` is followed by an existing expression @@ -201,7 +189,6 @@ Some features trigger on typing certain characters: === Parent Module **Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_ide/src/parent_module.rs[parent_module.rs] - Navigates to the parent module of the current module. |=== @@ -214,7 +201,6 @@ Navigates to the parent module of the current module. === Run **Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_ide/src/runnables.rs[runnables.rs] - Shows a popup suggesting to run a test/benchmark/binary **at the current cursor location**. Super useful for repeatedly running just a single test. Do bind this to a shortcut! @@ -229,7 +215,6 @@ to a shortcut! === Semantic Syntax Highlighting **Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_ide/src/syntax_highlighting.rs[syntax_highlighting.rs] - rust-analyzer highlights the code semantically. For example, `bar` in `foo::Bar` might be colored differently depending on whether `Bar` is an enum or a trait. rust-analyzer does not specify colors directly, instead it assigns tag (like `struct`) and a set of modifiers (like `declaration`) to each token. @@ -242,7 +227,6 @@ We also give special modifier for `mut` and `&mut` local variables. === Show Syntax Tree **Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_ide/src/syntax_tree.rs[syntax_tree.rs] - Shows the parse tree of the current file. It exists mostly for debugging rust-analyzer itself. @@ -256,7 +240,6 @@ rust-analyzer itself. === Status **Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_ide/src/status.rs[status.rs] - Shows internal statistic about memory usage of rust-analyzer. |=== @@ -269,7 +252,6 @@ Shows internal statistic about memory usage of rust-analyzer. === Structural Seach and Replace **Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_ide/src/ssr.rs[ssr.rs] - Search and replace with named wildcards that will match any expression. The syntax for a structural search replace command is ` ==>> `. A `$:expr` placeholder in the search pattern will match any expression and `$` will reference it in the replacement. @@ -295,7 +277,6 @@ String::from((y + 5).foo(z)) === Workspace Symbol **Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_ide_db/src/symbol_index.rs[symbol_index.rs] - Uses fuzzy-search to find types, modules and functions by name across your project and dependencies. This is **the** most useful feature, which improves code navigation tremendously. It mostly works on top of the built-in LSP -- cgit v1.2.3