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/features.md | 96 ------------------------- docs/user/generated_features.adoc | 143 ++++++++++++++++++++++++++++++++++++++ docs/user/readme.adoc | 1 + 3 files changed, 144 insertions(+), 96 deletions(-) delete mode 100644 docs/user/features.md (limited to 'docs/user') 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 @@ -This document is an index of features that the rust-analyzer language server -provides. Shortcuts are for the default VS Code layout. If there's no shortcut, -you can use Ctrl+Shift+P to search for the corresponding action. - -### Commands ctrl+shift+p - - -#### Toggle inlay hints - -Toggle inlay hints view for the current workspace. -It is recommended to assign a shortcut for this command to quickly turn off -inlay hints when they prevent you from reading/writing the code. - -### Magic Completions - -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: - -#### Inside Expressions - -- `pd` -> `println!("{:?}")` -- `ppd` -> `println!("{:#?}")` - -#### Inside Modules - -- `tfn` -> `#[test] fn f(){}` -- `tmod` -> -```rust -#[cfg(test)] -mod tests { - use super::*; - - #[test] - fn test_fn() {} -} -``` - -### Code Highlighting - -Experimental feature to let rust-analyzer highlight Rust code instead of using the -default highlighter. - -#### Rainbow Highlighting - -Experimental feature that, given code highlighting using rust-analyzer is -active, will pick unique colors for identifiers. - -### Code hints - -Rust-analyzer has two types of hints to show the information about the code: - -* hover hints, appearing on hover on any element. - -These contain extended information on the hovered language item. - -* inlay hints, shown near the element hinted directly in the editor. - -Two types of inlay hints are displayed currently: - -* type hints, displaying the minimal information on the type of the expression (if the information is available) -* method chaining hints, type information for multi-line method chains -* parameter name hints, displaying the names of the parameters in the corresponding methods - -#### VS Code - -In VS Code, the following settings can be used to configure the inlay hints: - -* `rust-analyzer.inlayHints.typeHints` - enable hints for inferred types. -* `rust-analyzer.inlayHints.chainingHints` - enable hints for inferred types on method chains. -* `rust-analyzer.inlayHints.parameterHints` - enable hints for function parameters. -* `rust-analyzer.inlayHints.maxLength` — shortens the hints if their length exceeds the value specified. If no value is specified (`null`), no shortening is applied. - -**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. -This approach has limitations, the caret movement and bracket highlighting near the edges of the hint may be weird: -[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 @@ +=== 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] 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 @@ :important-caption: :heavy_exclamation_mark: :caution-caption: :fire: :warning-caption: :warning: +:source-highlighter: rouge :experimental: // Master copy of this document lives in the https://github.com/rust-analyzer/rust-analyzer repository -- cgit v1.2.3