language-servers/rust-analyzer
1
0
Fork 0
mirror of https://github.com/rust-lang/rust-analyzer.git synced 2025-07-07 13:15:27 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 3

manual: Convert to mdbook

Browse source 
Split manual.adoc into markdown files, one for each chapter.

For the parts of the manual that are generated from source code doc
comments, update the comments to use markdown syntax and update the
code generators to write to `generated.md` files.

For the weekly release, stop copying the .adoc files to the
`rust-analyzer/rust-analyzer.github.io` at release time. Instead,
we'll sync the manual hourly from this repository.

See https://github.com/rust-analyzer/rust-analyzer.github.io/pull/226
for the sync. This PR should be merged first, and that PR needs to be
merged before the next weekly release.

This change is based on #15795, but rebased and updated. I've also
manually checked each page for markdown syntax issues and fixed any I
encountered.

Co-authored-by: Lukas Wirth <lukastw97@gmail.com>
Co-authored-by: Josh Rotenberg <joshrotenberg@gmail.com>
This commit is contained in:
Wilfred Hughes 2025-01-23 15:44:20 -08:00
parent 6e4c29f7ce
commit deda58e8f1
70 changed files with 2836 additions and 2686 deletions
Download patch file Download diff file Expand all files Collapse all files

7
.gitignore vendored
View file

@ -6,10 +6,11 @@ target/
*.log
*.iml
.vscode/settings.json
generated_assists.adoc
generated_features.adoc
generated_diagnostic.adoc
.DS_Store
/out/
/dump.lsif
.envrc
docs/book/book
docs/book/src/assists_generated.md
docs/book/src/diagnostics_generated.md
docs/book/src/features_generated.md

4
crates/ide-assists/src/handlers/apply_demorgan.rs
View file

@ -15,7 +15,7 @@ use crate::{utils::invert_boolean_expression, AssistContext, AssistId, AssistKin
// Assist: apply_demorgan
//
// Apply https://en.wikipedia.org/wiki/De_Morgan%27s_laws[De Morgan's law].
// Apply [De Morgan's law](https://en.wikipedia.org/wiki/De_Morgan%27s_laws).
// This transforms expressions of the form `!l || !r` into `!(l && r)`.
// This also works with `&&`. This assist can only be applied with the cursor
// on either `||` or `&&`.
@ -131,7 +131,7 @@ pub(crate) fn apply_demorgan(acc: &mut Assists, ctx: &AssistContext<'_>) -> Opti
// Assist: apply_demorgan_iterator
//
// Apply https://en.wikipedia.org/wiki/De_Morgan%27s_laws[De Morgan's law] to
// Apply [De Morgan's law](https://en.wikipedia.org/wiki/De_Morgan%27s_laws) to
// `Iterator::all` and `Iterator::any`.
//
// This transforms expressions of the form `!iter.any(|x| predicate(x))` into

6
crates/ide-assists/src/handlers/auto_import.rs
View file

@ -38,7 +38,7 @@ use crate::{AssistContext, AssistId, AssistKind, Assists, GroupLabel};
// use super::AssistContext;
// ```
//
// .Import Granularity
// #### Import Granularity
//
// It is possible to configure how use-trees are merged with the `imports.granularity.group` setting.
// It has the following configurations:
@ -54,7 +54,7 @@ use crate::{AssistContext, AssistId, AssistKind, Assists, GroupLabel};
//
// In `VS Code` the configuration for this is `rust-analyzer.imports.granularity.group`.
//
// .Import Prefix
// #### Import Prefix
//
// The style of imports in the same crate is configurable through the `imports.prefix` setting.
// It has the following configurations:
@ -68,7 +68,7 @@ use crate::{AssistContext, AssistId, AssistKind, Assists, GroupLabel};
//
// In `VS Code` the configuration for this is `rust-analyzer.imports.prefix`.
//
// image::https://user-images.githubusercontent.com/48062697/113020673-b85be580-917a-11eb-9022-59585f35d4f8.gif[]
// ![Auto Import](https://user-images.githubusercontent.com/48062697/113020673-b85be580-917a-11eb-9022-59585f35d4f8.gif)
// Assist: auto_import
//

2
crates/ide-assists/src/tests/generated.rs
View file

@ -1,4 +1,4 @@
//! Generated by `cargo codegen assists-doc-tests`, do not edit by hand.
//! Generated by `cargo xtask codegen assists-doc-tests`, do not edit by hand.
use super::check_doc_test;

8
crates/ide-completion/src/completions/flyimport.rs
View file

@ -83,19 +83,19 @@ use crate::{
// NOTE: currently, if an assoc item comes from a trait that's not currently imported, and it also has an unresolved and/or partially-qualified path,
// no imports will be proposed.
//
// .Fuzzy search details
// #### Fuzzy search details
//
// To avoid an excessive amount of the results returned, completion input is checked for inclusion in the names only
// (i.e. in `HashMap` in the `std::collections::HashMap` path).
// For the same reasons, avoids searching for any path imports for inputs with their length less than 2 symbols
// (but shows all associated items for any input length).
//
// .Import configuration
// #### Import configuration
//
// It is possible to configure how use-trees are merged with the `imports.granularity.group` setting.
// Mimics the corresponding behavior of the `Auto Import` feature.
//
// .LSP and performance implications
// #### LSP and performance implications
//
// The feature is enabled only if the LSP client supports LSP protocol version 3.16+ and reports the `additionalTextEdits`
// (case-sensitive) resolve client capability in its client capabilities.
@ -103,7 +103,7 @@ use crate::{
// For clients with no such support, all edits have to be calculated on the completion request, including the fuzzy search completion ones,
// which might be slow ergo the feature is automatically disabled.
//
// .Feature toggle
// #### Feature toggle
//
// The feature can be forcefully turned off in the settings with the `rust-analyzer.completion.autoimport.enable` flag.
// Note that having this flag set to `true` does not guarantee that the feature is enabled: your client needs to have the corresponding

2
crates/ide-completion/src/completions/postfix/format_like.rs
View file

@ -14,7 +14,7 @@
// ** `logw` -> `log::warn!(...)`
// ** `loge` -> `log::error!(...)`
//
// image::https://user-images.githubusercontent.com/48062697/113020656-b560f500-917a-11eb-87de-02991f61beb8.gif[]
// ![Format String Completion](https://user-images.githubusercontent.com/48062697/113020656-b560f500-917a-11eb-87de-02991f61beb8.gif)
use ide_db::{
syntax_helpers::format_string_exprs::{parse_format_exprs, with_placeholders, Arg},

8
crates/ide-completion/src/lib.rs
View file

@ -110,11 +110,13 @@ impl CompletionFieldsToResolve {
//
// There also snippet completions:
//
// .Expressions
// #### Expressions
//
// - `pd` -> `eprintln!(" = {:?}", );`
// - `ppd` -> `eprintln!(" = {:#?}", );`
//
// .Items
// #### Items
//
// - `tfn` -> `#[test] fn feature(){}`
// - `tmod` ->
// ```rust
@ -131,7 +133,7 @@ impl CompletionFieldsToResolve {
// Those are the additional completion options with automatic `use` import and options from all project importable items,
// fuzzy matched against the completion input.
//
// image::https://user-images.githubusercontent.com/48062697/113020667-b72ab880-917a-11eb-8778-716cf26a0eb3.gif[]
// ![Magic Completions](https://user-images.githubusercontent.com/48062697/113020667-b72ab880-917a-11eb-8778-716cf26a0eb3.gif)
/// Main entry point for completion. We run completion as a two-phase process.
///

12
crates/ide-completion/src/snippet.rs
View file

@ -8,8 +8,7 @@
//
// A custom snippet can be defined by adding it to the `rust-analyzer.completion.snippets.custom` object respectively.
//
// [source,json]
// ----
// ```json
// {
// "rust-analyzer.completion.snippets.custom": {
// "thread spawn": {
@ -25,7 +24,7 @@
// }
// }
// }
// ----
// ```
//
// In the example above:
//
@ -39,6 +38,7 @@
// * `description` is an optional description of the snippet, if unset the snippet name will be used.
//
// * `requires` is an optional list of item paths that have to be resolvable in the current crate where the completion is rendered.
// On failure of resolution the snippet won't be applicable, otherwise the snippet will insert an import for the items on insertion if
// the items aren't yet in scope.
//
@ -55,8 +55,8 @@
//
// For the VSCode editor, rust-analyzer also ships with a small set of defaults which can be removed
// by overwriting the settings object mentioned above, the defaults are:
// [source,json]
// ----
//
// ```json
// {
// "Arc::new": {
// "postfix": "arc",
@ -98,7 +98,7 @@
// "scope": "expr"
// }
// }
// ----
// ````
use hir::{ModPath, Name, Symbol};
use ide_db::imports::import_assets::LocatedImport;

9
crates/ide-db/src/apply_change.rs
View file

@ -44,12 +44,11 @@ impl RootDatabase {
//
// Clears rust-analyzer's internal database and prints memory usage statistics.
//
// |===
// | Editor | Action Name
//
// | Editor | Action Name |
// |---------|-------------|
// | VS Code | **rust-analyzer: Memory Usage (Clears Database)**
// |===
// image::https://user-images.githubusercontent.com/48062697/113065592-08559f00-91b1-11eb-8c96-64b88068ec02.gif[]
// ![Memory Usage](https://user-images.githubusercontent.com/48062697/113065592-08559f00-91b1-11eb-8c96-64b88068ec02.gif)
pub fn per_query_memory_usage(&mut self) -> Vec<(String, Bytes, usize)> {
let mut acc: Vec<(String, Bytes, usize)> = vec![];

8
crates/ide-db/src/symbol_index.rs
View file

@ -193,11 +193,9 @@ impl<DB> std::ops::Deref for Snap<DB> {
// `rust-analyzer.workspace.symbol.search.kind` settings. Symbols prefixed
// with `__` are hidden from the search results unless configured otherwise.
//
// |===
// | Editor | Shortcut
//
// | VS Code | kbd:[Ctrl+T]
// |===
// | Editor | Shortcut |
// |---------|-----------|
// | VS Code | <kbd>Ctrl+T</kbd>
pub fn world_symbols(db: &RootDatabase, query: Query) -> Vec<FileSymbol> {
let _p = tracing::info_span!("world_symbols", query = ?query.query).entered();

2
crates/ide-diagnostics/src/handlers/incorrect_case.rs
View file

@ -12,7 +12,7 @@ use crate::{
// Diagnostic: incorrect-ident-case
//
// This diagnostic is triggered if an item name doesn't follow https://doc.rust-lang.org/1.0.0/style/style/naming/README.html[Rust naming convention].
// This diagnostic is triggered if an item name doesn't follow [Rust naming convention](https://doc.rust-lang.org/1.0.0/style/style/naming/README.html).
pub(crate) fn incorrect_case(ctx: &DiagnosticsContext<'_>, d: &hir::IncorrectCase) -> Diagnostic {
let code = match d.expected_case {
CaseType::LowerSnakeCase => DiagnosticCode::RustcLint("non_snake_case"),

18
crates/ide-ssr/src/lib.rs
View file

@ -33,12 +33,10 @@
//
// Supported constraints:
//
// |===
// | Constraint | Restricts placeholder
//
// | kind(literal) | Is a literal (e.g. `42` or `"forty two"`)
// | not(a) | Negates the constraint `a`
// |===
// | Constraint | Restricts placeholder |
// |---------------|------------------------|
// | kind(literal) | Is a literal (e.g. `42` or `"forty two"`) |
// | not(a) | Negates the constraint `a` |
//
// Available via the command `rust-analyzer.ssr`.
//
@ -52,11 +50,9 @@
// String::from((y + 5).foo(z))
// ```
//
// |===
// | Editor | Action Name
//
// | VS Code | **rust-analyzer: Structural Search Replace**
// |===
// | Editor | Action Name |
// |---------|--------------|
// | VS Code | **rust-analyzer: Structural Search Replace** |
//
// Also available as an assist, by writing a comment containing the structural
// search and replace rule. You will only see the assist if the comment can

2
crates/ide/src/annotations.rs
View file

@ -21,7 +21,7 @@ mod fn_references;
// Provides user with annotations above items for looking up references or impl blocks
// and running/debugging binaries.
//
// image::https://user-images.githubusercontent.com/48062697/113020672-b7c34f00-917a-11eb-8f6e-858735660a0e.png[]
// ![Annotations](https://user-images.githubusercontent.com/48062697/113020672-b7c34f00-917a-11eb-8f6e-858735660a0e.png)
#[derive(Debug, Hash, PartialEq, Eq)]
pub struct Annotation {
pub range: TextRange,

8
crates/ide/src/doc_links.rs
View file

@ -122,11 +122,9 @@ pub(crate) fn remove_links(markdown: &str) -> String {
// The simplest way to use this feature is via the context menu. Right-click on
// the selected item. The context menu opens. Select **Open Docs**.
//
// |===
// | Editor | Action Name
//
// | VS Code | **rust-analyzer: Open Docs**
// |===
// | Editor | Action Name |
// |---------|-------------|
// | VS Code | **rust-analyzer: Open Docs** |
pub(crate) fn external_docs(
db: &RootDatabase,
FilePosition { file_id, offset }: FilePosition,

10
crates/ide/src/expand_macro.rs
View file

@ -19,13 +19,11 @@ pub struct ExpandedMacro {
//
// Shows the full macro expansion of the macro at the current caret position.
//
// |===
// | Editor | Action Name
// | Editor | Action Name |
// |---------|-------------|
// | VS Code | **rust-analyzer: Expand macro recursively at caret** |
//
// | VS Code | **rust-analyzer: Expand macro recursively at caret**
// |===
//
// image::https://user-images.githubusercontent.com/48062697/113020648-b3973180-917a-11eb-84a9-ecb921293dc5.gif[]
// ![Expand Macro Recursively](https://user-images.githubusercontent.com/48062697/113020648-b3973180-917a-11eb-84a9-ecb921293dc5.gif)
pub(crate) fn expand_macro(db: &RootDatabase, position: FilePosition) -> Option<ExpandedMacro> {
let sema = Semantics::new(db);
let file = sema.parse_guess_edition(position.file_id);

10
crates/ide/src/extend_selection.rs
View file

@ -17,13 +17,11 @@ use crate::FileRange;
// Extends or shrinks the current selection to the encompassing syntactic construct
// (expression, statement, item, module, etc). It works with multiple cursors.
//
// |===
// | Editor | Shortcut
// | Editor | Shortcut |
// |---------|----------|
// | VS Code | <kbd>Alt+Shift+→</kbd>, <kbd>Alt+Shift+←</kbd> |
//
// | VS Code | kbd:[Alt+Shift+→], kbd:[Alt+Shift+←]
// |===
//
// image::https://user-images.githubusercontent.com/48062697/113020651-b42fc800-917a-11eb-8a4f-cf1a07859fac.gif[]
// ![Expand and Shrink Selection](https://user-images.githubusercontent.com/48062697/113020651-b42fc800-917a-11eb-8a4f-cf1a07859fac.gif)
pub(crate) fn extend_selection(db: &RootDatabase, frange: FileRange) -> TextRange {
let sema = Semantics::new(db);
let src = sema.parse_guess_edition(frange.file_id);

10
crates/ide/src/fetch_crates.rs
View file

@ -14,13 +14,11 @@ pub struct CrateInfo {
//
// Shows a view tree with all the dependencies of this project
//
// |===
// | Editor | Panel Name
// | Editor | Panel Name |
// |---------|------------|
// | VS Code | **Rust Dependencies** |
//
// | VS Code | **Rust Dependencies**
// |===
//
// image::https://user-images.githubusercontent.com/5748995/229394139-2625beab-f4c9-484b-84ed-ad5dee0b1e1a.png[]
// ![Show Dependency Tree](https://user-images.githubusercontent.com/5748995/229394139-2625beab-f4c9-484b-84ed-ad5dee0b1e1a.png)
pub(crate) fn fetch_crates(db: &RootDatabase) -> FxIndexSet<CrateInfo> {
let crate_graph = db.crate_graph();
crate_graph

11
crates/ide/src/file_structure.rs
View file

@ -31,14 +31,11 @@ pub enum StructureNodeKind {
// * draw breadcrumbs to describe the context around the cursor
// * draw outline of the file
//
// |===
// | Editor | Shortcut
// | Editor | Shortcut |
// |---------|----------|
// | VS Code | <kbd>Ctrl+Shift+O</kbd> |
//
// | VS Code | kbd:[Ctrl+Shift+O]
// |===
//
// image::https://user-images.githubusercontent.com/48062697/113020654-b42fc800-917a-11eb-8388-e7dc4d92b02e.gif[]
// ![File Structure](https://user-images.githubusercontent.com/48062697/113020654-b42fc800-917a-11eb-8388-e7dc4d92b02e.gif)
pub(crate) fn file_structure(file: &SourceFile) -> Vec<StructureNode> {
let mut res = Vec::new();
let mut stack = Vec::new();

10
crates/ide/src/goto_definition.rs
View file

@ -31,13 +31,11 @@ use syntax::{
//
// For outline modules, this will navigate to the source file of the module.
//
// |===
// | Editor | Shortcut
// | Editor | Shortcut |
// |---------|----------|
// | VS Code | <kbd>F12</kbd> |
//
// | VS Code | kbd:[F12]
// |===
//
// image::https://user-images.githubusercontent.com/48062697/113065563-025fbe00-91b1-11eb-83e4-a5a703610b23.gif[]
// ![Go to Definition](https://user-images.githubusercontent.com/48062697/113065563-025fbe00-91b1-11eb-83e4-a5a703610b23.gif)
pub(crate) fn goto_definition(
db: &RootDatabase,
FilePosition { file_id, offset }: FilePosition,

10
crates/ide/src/goto_implementation.rs
View file

@ -12,13 +12,11 @@ use crate::{FilePosition, NavigationTarget, RangeInfo, TryToNav};
//
// Navigates to the impl items of types.
//
// |===
// | Editor | Shortcut
// | Editor | Shortcut |
// |---------|----------|
// | VS Code | <kbd>Ctrl+F12</kbd>
//
// | VS Code | kbd:[Ctrl+F12]
// |===
//
// image::https://user-images.githubusercontent.com/48062697/113065566-02f85480-91b1-11eb-9288-aaad8abd8841.gif[]
// ![Go to Implementation](https://user-images.githubusercontent.com/48062697/113065566-02f85480-91b1-11eb-9288-aaad8abd8841.gif)
pub(crate) fn goto_implementation(
db: &RootDatabase,
FilePosition { file_id, offset }: FilePosition,

10
crates/ide/src/goto_type_definition.rs
View file

@ -8,13 +8,11 @@ use crate::{FilePosition, NavigationTarget, RangeInfo, TryToNav};
//
// Navigates to the type of an identifier.
//
// |===
// | Editor | Action Name
// | Editor | Action Name |
// |---------|-------------|
// | VS Code | **Go to Type Definition** |
//
// | VS Code | **Go to Type Definition**
// |===
//
// image::https://user-images.githubusercontent.com/48062697/113020657-b560f500-917a-11eb-9007-0f809733a338.gif[]
// ![Go to Type Definition](https://user-images.githubusercontent.com/48062697/113020657-b560f500-917a-11eb-9007-0f809733a338.gif)
pub(crate) fn goto_type_definition(
db: &RootDatabase,
FilePosition { file_id, offset }: FilePosition,

12
crates/ide/src/highlight_related.rs
View file

@ -43,12 +43,12 @@ pub struct HighlightRelatedConfig {
//
// Highlights constructs related to the thing under the cursor:
//
// . if on an identifier, highlights all references to that identifier in the current file
// .. additionally, if the identifier is a trait in a where clause, type parameter trait bound or use item, highlights all references to that trait's assoc items in the corresponding scope
// . if on an `async` or `await` token, highlights all yield points for that async context
// . if on a `return` or `fn` keyword, `?` character or `->` return type arrow, highlights all exit points for that context
// . if on a `break`, `loop`, `while` or `for` token, highlights all break points for that loop or block context
// . if on a `move` or `|` token that belongs to a closure, highlights all captures of the closure.
// 1. if on an identifier, highlights all references to that identifier in the current file
// * additionally, if the identifier is a trait in a where clause, type parameter trait bound or use item, highlights all references to that trait's assoc items in the corresponding scope
// 1. if on an `async` or `await` token, highlights all yield points for that async context
// 1. if on a `return` or `fn` keyword, `?` character or `->` return type arrow, highlights all exit points for that context
// 1. if on a `break`, `loop`, `while` or `for` token, highlights all break points for that loop or block context
// 1. if on a `move` or `|` token that belongs to a closure, highlights all captures of the closure.
//
// Note: `?`, `|` and `->` do not currently trigger this behavior in the VSCode editor.
pub(crate) fn highlight_related(

2
crates/ide/src/hover.rs
View file

@ -118,7 +118,7 @@ pub struct HoverResult {
// Shows additional information, like the type of an expression or the documentation for a definition when "focusing" code.
// Focusing is usually hovering with a mouse, but can also be triggered with a shortcut.
//
// image::https://user-images.githubusercontent.com/48062697/113020658-b5f98b80-917a-11eb-9f88-3dbc27320c95.gif[]
// ![Hover](https://user-images.githubusercontent.com/48062697/113020658-b5f98b80-917a-11eb-9f88-3dbc27320c95.gif)
pub(crate) fn hover(
db: &RootDatabase,
frange @ FileRange { file_id, range }: FileRange,

8
crates/ide/src/inlay_hints.rs
View file

@ -59,7 +59,7 @@ mod range_exclusive;
//
// Note: inlay hints for function argument names are heuristically omitted to reduce noise and will not appear if
// any of the
// link:https://github.com/rust-lang/rust-analyzer/blob/6b8b8ff4c56118ddee6c531cde06add1aad4a6af/crates/ide/src/inlay_hints/param_name.rs#L92-L99[following criteria]
// [following criteria](https://github.com/rust-lang/rust-analyzer/blob/6b8b8ff4c56118ddee6c531cde06add1aad4a6af/crates/ide/src/inlay_hints/param_name.rs#L92-L99)
// are met:
//
// * the parameter name is a suffix of the function's name
@ -68,13 +68,13 @@ mod range_exclusive;
// of argument with _ splitting it off
// * the parameter name starts with `ra_fixture`
// * the parameter name is a
// link:https://github.com/rust-lang/rust-analyzer/blob/6b8b8ff4c56118ddee6c531cde06add1aad4a6af/crates/ide/src/inlay_hints/param_name.rs#L200[well known name]
// [well known name](https://github.com/rust-lang/rust-analyzer/blob/6b8b8ff4c56118ddee6c531cde06add1aad4a6af/crates/ide/src/inlay_hints/param_name.rs#L200)
// in a unary function
// * the parameter name is a
// link:https://github.com/rust-lang/rust-analyzer/blob/6b8b8ff4c56118ddee6c531cde06add1aad4a6af/crates/ide/src/inlay_hints/param_name.rs#L201[single character]
// [single character](https://github.com/rust-lang/rust-analyzer/blob/6b8b8ff4c56118ddee6c531cde06add1aad4a6af/crates/ide/src/inlay_hints/param_name.rs#L201)
// in a unary function
//
// image::https://user-images.githubusercontent.com/48062697/113020660-b5f98b80-917a-11eb-8d70-3be3fd558cdd.png[]
// ![Inlay hints](https://user-images.githubusercontent.com/48062697/113020660-b5f98b80-917a-11eb-8d70-3be3fd558cdd.png)
pub(crate) fn inlay_hints(
db: &RootDatabase,
file_id: FileId,

8
crates/ide/src/interpret.rs
View file

@ -7,11 +7,9 @@ use syntax::{algo::ancestors_at_offset, ast, AstNode, TextRange};
// Feature: Interpret A Function, Static Or Const.
//
// |===
// | Editor | Action Name
//
// | VS Code | **rust-analyzer: Interpret**
// |===
// | Editor | Action Name |
// |---------|-------------|
// | VS Code | **rust-analyzer: Interpret** |
pub(crate) fn interpret(db: &RootDatabase, position: FilePosition) -> String {
match find_and_interpret(db, position) {
Some((duration, mut result)) => {

14
crates/ide/src/join_lines.rs
View file

@ -21,17 +21,13 @@ pub struct JoinLinesConfig {
//
// Join selected lines into one, smartly fixing up whitespace, trailing commas, and braces.
//
// See
// https://user-images.githubusercontent.com/1711539/124515923-4504e800-dde9-11eb-8d58-d97945a1a785.gif[this gif]
// for the cases handled specially by joined lines.
// See [this gif](https://user-images.githubusercontent.com/1711539/124515923-4504e800-dde9-11eb-8d58-d97945a1a785.gif) for the cases handled specially by joined lines.
//
// |===
// | Editor | Action Name
// | Editor | Action Name |
// |---------|-------------|
// | VS Code | **rust-analyzer: Join lines** |
//
// | VS Code | **rust-analyzer: Join lines**
// |===
//
// image::https://user-images.githubusercontent.com/48062697/113020661-b6922200-917a-11eb-87c4-b75acc028f11.gif[]
// ![Join Lines](https://user-images.githubusercontent.com/48062697/113020661-b6922200-917a-11eb-87c4-b75acc028f11.gif)
pub(crate) fn join_lines(
config: &JoinLinesConfig,
file: &SourceFile,

10
crates/ide/src/matching_brace.rs
View file

@ -9,13 +9,11 @@ use syntax::{
// 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
// | Editor | Action Name |
// |---------|-------------|
// | VS Code | **rust-analyzer: Find matching brace** |
//
// | VS Code | **rust-analyzer: Find matching brace**
// |===
//
// image::https://user-images.githubusercontent.com/48062697/113065573-04298180-91b1-11eb-8dec-d4e2a202f304.gif[]
// ![Matching Brace](https://user-images.githubusercontent.com/48062697/113065573-04298180-91b1-11eb-8dec-d4e2a202f304.gif)
pub(crate) fn matching_brace(file: &SourceFile, offset: TextSize) -> Option<TextSize> {
const BRACES: &[SyntaxKind] =
&[T!['{'], T!['}'], T!['['], T![']'], T!['('], T![')'], T![<], T![>], T![|], T![|]];

8
crates/ide/src/move_item.rs
View file

@ -17,14 +17,12 @@ pub enum Direction {
//
// Move item under cursor or selection up and down.
//
// |===
// | Editor | Action Name
//
// | Editor | Action Name |
// |---------|-------------|
// | VS Code | **rust-analyzer: Move item up**
// | VS Code | **rust-analyzer: Move item down**
// |===
//
// image::https://user-images.githubusercontent.com/48062697/113065576-04298180-91b1-11eb-91ce-4505e99ed598.gif[]
// ![Move Item](https://user-images.githubusercontent.com/48062697/113065576-04298180-91b1-11eb-91ce-4505e99ed598.gif)
pub(crate) fn move_item(
db: &RootDatabase,
range: FileRange,

10
crates/ide/src/parent_module.rs
View file

@ -15,13 +15,11 @@ use crate::NavigationTarget;
//
// Navigates to the parent module of the current module.
//
// |===
// | Editor | Action Name
// | Editor | Action Name |
// |---------|-------------|
// | VS Code | **rust-analyzer: Locate parent module** |
//
// | VS Code | **rust-analyzer: Locate parent module**
// |===
//
// image::https://user-images.githubusercontent.com/48062697/113065580-04c21800-91b1-11eb-9a32-00086161c0bd.gif[]
// ![Parent Module](https://user-images.githubusercontent.com/48062697/113065580-04c21800-91b1-11eb-9a32-00086161c0bd.gif)
/// This returns `Vec` because a module may be included from several places.
pub(crate) fn parent_module(db: &RootDatabase, position: FilePosition) -> Vec<NavigationTarget> {

10
crates/ide/src/references.rs
View file

@ -43,13 +43,11 @@ pub struct Declaration {
//
// Shows all references of the item at the cursor location
//
// |===
// | Editor | Shortcut
// | Editor | Shortcut |
// |---------|----------|
// | VS Code | <kbd>Shift+Alt+F12</kbd> |
//
// | VS Code | kbd:[Shift+Alt+F12]
// |===
//
// image::https://user-images.githubusercontent.com/48062697/113020670-b7c34f00-917a-11eb-8003-370ac5f2b3cb.gif[]
// ![Find All References](https://user-images.githubusercontent.com/48062697/113020670-b7c34f00-917a-11eb-8003-370ac5f2b3cb.gif)
pub(crate) fn find_all_refs(
sema: &Semantics<'_, RootDatabase>,
position: FilePosition,

10
crates/ide/src/rename.rs
View file

@ -71,13 +71,11 @@ pub(crate) fn prepare_rename(
//
// Renames the item below the cursor and all of its references
//
// |===
// | Editor | Shortcut
// | Editor | Shortcut |
// |---------|----------|
// | VS Code | <kbd>F2</kbd> |
//
// | VS Code | kbd:[F2]
// |===
//
// image::https://user-images.githubusercontent.com/48062697/113065582-055aae80-91b1-11eb-8ade-2b58e6d81883.gif[]
// ![Rename](https://user-images.githubusercontent.com/48062697/113065582-055aae80-91b1-11eb-8ade-2b58e6d81883.gif)
pub(crate) fn rename(
db: &RootDatabase,
position: FilePosition,

17
crates/ide/src/runnables.rs
View file

@ -119,12 +119,11 @@ impl Runnable {
// location**. Super useful for repeatedly running just a single test. Do bind this
// to a shortcut!
//
// |===
// | Editor | Action Name
// | Editor | Action Name |
// |---------|-------------|
// | VS Code | **rust-analyzer: Run** |
//
// | VS Code | **rust-analyzer: Run**
// |===
// image::https://user-images.githubusercontent.com/48062697/113065583-055aae80-91b1-11eb-958f-d67efcaf6a2f.gif[]
// ![Run](https://user-images.githubusercontent.com/48062697/113065583-055aae80-91b1-11eb-958f-d67efcaf6a2f.gif)
pub(crate) fn runnables(db: &RootDatabase, file_id: FileId) -> Vec<Runnable> {
let sema = Semantics::new(db);
@ -207,11 +206,9 @@ pub(crate) fn runnables(db: &RootDatabase, file_id: FileId) -> Vec<Runnable> {
// The simplest way to use this feature is via the context menu. Right-click on
// the selected item. The context menu opens. Select **Peek Related Tests**.
//
// |===
// | Editor | Action Name
//
// | VS Code | **rust-analyzer: Peek Related Tests**
// |===
// | Editor | Action Name |
// |---------|-------------|
// | VS Code | **rust-analyzer: Peek Related Tests** |
pub(crate) fn related_tests(
db: &RootDatabase,
position: FilePosition,

9
crates/ide/src/status.rs
View file

@ -29,12 +29,11 @@ use triomphe::Arc;
//
// Shows internal statistic about memory usage of rust-analyzer.
//
// |===
// | Editor | Action Name
// | Editor | Action Name |
// |---------|-------------|
// | VS Code | **rust-analyzer: Status** |
//
// | VS Code | **rust-analyzer: Status**
// |===
// image::https://user-images.githubusercontent.com/48062697/113065584-05f34500-91b1-11eb-98cc-5c196f76be7f.gif[]
// ![Status](https://user-images.githubusercontent.com/48062697/113065584-05f34500-91b1-11eb-98cc-5c196f76be7f.gif)
pub(crate) fn status(db: &RootDatabase, file_id: Option<FileId>) -> String {
let mut buf = String::new();

179
crates/ide/src/syntax_highlighting.rs
View file

@ -76,113 +76,118 @@ pub struct HighlightConfig {
// We also give special modifier for `mut` and `&mut` local variables.
//
//
// .Token Tags
// #### Token Tags
//
// Rust-analyzer currently emits the following token tags:
//
// - For items:
// +
// [horizontal]
// attribute:: Emitted for attribute macros.
// enum:: Emitted for enums.
// function:: Emitted for free-standing functions.
// derive:: Emitted for derive macros.
// macro:: Emitted for function-like macros.
// method:: Emitted for associated functions, also knowns as methods.
// namespace:: Emitted for modules.
// struct:: Emitted for structs.
// trait:: Emitted for traits.
// typeAlias:: Emitted for type aliases and `Self` in `impl`s.
// union:: Emitted for unions.
//
// | | |
// |-----------|--------------------------------|
// | attribute | Emitted for attribute macros. |
// |enum| Emitted for enums. |
// |function| Emitted for free-standing functions. |
// |derive| Emitted for derive macros. |
// |macro| Emitted for function-like macros. |
// |method| Emitted for associated functions, also knowns as methods. |
// |namespace| Emitted for modules. |
// |struct| Emitted for structs.|
// |trait| Emitted for traits.|
// |typeAlias| Emitted for type aliases and `Self` in `impl`s.|
// |union| Emitted for unions.|
//
// - For literals:
// +
// [horizontal]
// boolean:: Emitted for the boolean literals `true` and `false`.
// character:: Emitted for character literals.
// number:: Emitted for numeric literals.
// string:: Emitted for string literals.
// escapeSequence:: Emitted for escaped sequences inside strings like `\n`.
// formatSpecifier:: Emitted for format specifiers `{:?}` in `format!`-like macros.
//
// | | |
// |-----------|--------------------------------|
// | boolean| Emitted for the boolean literals `true` and `false`.|
// | character| Emitted for character literals.|
// | number| Emitted for numeric literals.|
// | string| Emitted for string literals.|
// | escapeSequence| Emitted for escaped sequences inside strings like `\n`.|
// | formatSpecifier| Emitted for format specifiers `{:?}` in `format!`-like macros.|
//
// - For operators:
// +
// [horizontal]
// operator:: Emitted for general operators.
// arithmetic:: Emitted for the arithmetic operators `+`, `-`, `*`, `/`, `+=`, `-=`, `*=`, `/=`.
// bitwise:: Emitted for the bitwise operators `|`, `&`, `!`, `^`, `|=`, `&=`, `^=`.
// comparison:: Emitted for the comparison operators `>`, `<`, `==`, `>=`, `<=`, `!=`.
// logical:: Emitted for the logical operators `||`, `&&`, `!`.
//
// | | |
// |-----------|--------------------------------|
// |operator| Emitted for general operators.|
// |arithmetic| Emitted for the arithmetic operators `+`, `-`, `*`, `/`, `+=`, `-=`, `*=`, `/=`.|
// |bitwise| Emitted for the bitwise operators `|`, `&`, `!`, `^`, `|=`, `&=`, `^=`.|
// |comparison| Emitted for the comparison oerators `>`, `<`, `==`, `>=`, `<=`, `!=`.|
// |logical| Emitted for the logical operatos `||`, `&&`, `!`.|
//
// - For punctuation:
// +
// [horizontal]
// punctuation:: Emitted for general punctuation.
// attributeBracket:: Emitted for attribute invocation brackets, that is the `#[` and `]` tokens.
// angle:: Emitted for `<>` angle brackets.
// brace:: Emitted for `{}` braces.
// bracket:: Emitted for `[]` brackets.
// parenthesis:: Emitted for `()` parentheses.
// colon:: Emitted for the `:` token.
// comma:: Emitted for the `,` token.
// dot:: Emitted for the `.` token.
// semi:: Emitted for the `;` token.
// macroBang:: Emitted for the `!` token in macro calls.
//
// //-
// | | |
// |-----------|--------------------------------|
// |punctuation| Emitted for general punctuation.|
// |attributeBracket| Emitted for attribute invocation brackets, that is the `#[` and `]` tokens.|
// |angle| Emitted for `<>` angle brackets.|
// |brace| Emitted for `{}` braces.|
// |bracket| Emitted for `[]` brackets.|
// |parenthesis| Emitted for `()` parentheses.|
// |colon| Emitted for the `:` token.|
// |comma| Emitted for the `,` token.|
// |dot| Emitted for the `.` token.|
// |semi| Emitted for the `;` token.|
// |macroBang| Emitted for the `!` token in macro calls.|
//
// [horizontal]
// builtinAttribute:: Emitted for names to builtin attributes in attribute path, the `repr` in `#[repr(u8)]` for example.
// builtinType:: Emitted for builtin types like `u32`, `str` and `f32`.
// comment:: Emitted for comments.
// constParameter:: Emitted for const parameters.
// deriveHelper:: Emitted for derive helper attributes.
// enumMember:: Emitted for enum variants.
// generic:: Emitted for generic tokens that have no mapping.
// keyword:: Emitted for keywords.
// label:: Emitted for labels.
// lifetime:: Emitted for lifetimes.
// parameter:: Emitted for non-self function parameters.
// property:: Emitted for struct and union fields.
// selfKeyword:: Emitted for the self function parameter and self path-specifier.
// selfTypeKeyword:: Emitted for the Self type parameter.
// toolModule:: Emitted for tool modules.
// typeParameter:: Emitted for type parameters.
// unresolvedReference:: Emitted for unresolved references, names that rust-analyzer can't find the definition of.
// variable:: Emitted for locals, constants and statics.
//-
//
// | | |
// |-----------|--------------------------------|
// |builtinAttribute| Emitted for names to builtin attributes in attribute path, the `repr` in `#[repr(u8)]` for example.|
// |builtinType| Emitted for builtin types like `u32`, `str` and `f32`.|
// |comment| Emitted for comments.|
// |constParameter| Emitted for const parameters.|
// |deriveHelper| Emitted for derive helper attributes.|
// |enumMember| Emitted for enum variants.|
// |generic| Emitted for generic tokens that have no mapping.|
// |keyword| Emitted for keywords.|
// |label| Emitted for labels.|
// |lifetime| Emitted for lifetimes.|
// |parameter| Emitted for non-self function parameters.|
// |property| Emitted for struct and union fields.|
// |selfKeyword| Emitted for the self function parameter and self path-specifier.|
// |selfTypeKeyword| Emitted for the Self type parameter.|
// |toolModule| Emitted for tool modules.|
// |typeParameter| Emitted for type parameters.|
// |unresolvedReference| Emitted for unresolved references, names that rust-analyzer can't find the definition of.|
// |variable| Emitted for locals, constants and statics.|
//
//
// .Token Modifiers
// #### Token Modifiers
//
// Token modifiers allow to style some elements in the source code more precisely.
//
// Rust-analyzer currently emits the following token modifiers:
//
// [horizontal]
// async:: Emitted for async functions and the `async` and `await` keywords.
// attribute:: Emitted for tokens inside attributes.
// callable:: Emitted for locals whose types implements one of the `Fn*` traits.
// constant:: Emitted for consts.
// consuming:: Emitted for locals that are being consumed when use in a function call.
// controlFlow:: Emitted for control-flow related tokens, this includes the `?` operator.
// crateRoot:: Emitted for crate names, like `serde` and `crate`.
// declaration:: Emitted for names of definitions, like `foo` in `fn foo() {}`.
// defaultLibrary:: Emitted for items from built-in crates (std, core, alloc, test and proc_macro).
// documentation:: Emitted for documentation comments.
// injected:: Emitted for doc-string injected highlighting like rust source blocks in documentation.
// intraDocLink:: Emitted for intra doc links in doc-strings.
// library:: Emitted for items that are defined outside of the current crate.
// macro:: Emitted for tokens inside macro calls.
// mutable:: Emitted for mutable locals and statics as well as functions taking `&mut self`.
// public:: Emitted for items that are from the current crate and are `pub`.
// reference:: Emitted for locals behind a reference and functions taking `self` by reference.
// static:: Emitted for "static" functions, also known as functions that do not take a `self` param, as well as statics and consts.
// trait:: Emitted for associated trait items.
// unsafe:: Emitted for unsafe operations, like unsafe function calls, as well as the `unsafe` token.
// | | |
// |-----------|--------------------------------|
// |async| Emitted for async functions and the `async` and `await` keywords.|
// |attribute| Emitted for tokens inside attributes.|
// |callable| Emitted for locals whose types implements one of the `Fn*` traits.|
// |constant| Emitted for const.|
// |consuming| Emitted for locals that are being consumed when use in a function call.|
// |controlFlow| Emitted for control-flow related tokens, this includes th `?` operator.|
// |crateRoot| Emitted for crate names, like `serde` and `crate.|
// |declaration| Emitted for names of definitions, like `foo` in `fn foo(){}`.|
// |defaultLibrary| Emitted for items from built-in crates (std, core, allc, test and proc_macro).|
// |documentation| Emitted for documentation comment.|
// |injected| Emitted for doc-string injected highlighting like rust source blocks in documentation.|
// |intraDocLink| Emitted for intra doc links in doc-string.|
// |library| Emitted for items that are defined outside of the current crae.|
// |macro| Emitted for tokens inside macro call.|
// |mutable| Emitted for mutable locals and statics as well as functions taking `&mut self`.|
// |public| Emitted for items that are from the current crate and are `pub.|
// |reference| Emitted for locals behind a reference and functions taking self` by reference.|
// |static| Emitted for "static" functions, also known as functions that d not take a `self` param, as well as statics and consts.|
// |trait| Emitted for associated trait item.|
// |unsafe| Emitted for unsafe operations, like unsafe function calls, as ell as the `unsafe` token.|
//
//
// image::https://user-images.githubusercontent.com/48062697/113164457-06cfb980-9239-11eb-819b-0f93e646acf8.png[]
// image::https://user-images.githubusercontent.com/48062697/113187625-f7f50100-9250-11eb-825e-91c58f236071.png[]
// ![Semantic Syntax Highlighting](https://user-images.githubusercontent.com/48062697/113164457-06cfb980-9239-11eb-819b-0f93e646acf8.png)
// ![Semantic Syntax Highlighting](https://user-images.githubusercontent.com/48062697/113187625-f7f50100-9250-11eb-825e-91c58f236071.png)
pub(crate) fn highlight(
db: &RootDatabase,
config: HighlightConfig,

11
crates/ide/src/typing.rs
View file

@ -51,16 +51,15 @@ struct ExtendedTextEdit {
// - typing `{` in a use item adds a closing `}` in the right place
// - typing `>` to complete a return type `->` will insert a whitespace after it
//
// VS Code::
// #### VS Code
//
// Add the following to `settings.json`:
// [source,json]
// ----
// ```json
// "editor.formatOnType": true,
// ----
// ```
//
// image::https://user-images.githubusercontent.com/48062697/113166163-69758500-923a-11eb-81ee-eb33ec380399.gif[]
// image::https://user-images.githubusercontent.com/48062697/113171066-105c2000-923f-11eb-87ab-f4a263346567.gif[]
// ![On Typing Assists](https://user-images.githubusercontent.com/48062697/113166163-69758500-923a-11eb-81ee-eb33ec380399.gif)
// ![On Typing Assists](https://user-images.githubusercontent.com/48062697/113171066-105c2000-923f-11eb-87ab-f4a263346567.gif)
pub(crate) fn on_char_typed(
db: &RootDatabase,
position: FilePosition,

24
crates/ide/src/typing/on_enter.rs
View file

@ -16,12 +16,12 @@ use ide_db::text_edit::TextEdit;
// Feature: On Enter
//
// rust-analyzer can override kbd:[Enter] key to make it smarter:
// rust-analyzer can override <kbd>Enter</kbd> key to make it smarter:
//
// - kbd:[Enter] inside triple-slash comments automatically inserts `///`
// - kbd:[Enter] in the middle or after a trailing space in `//` inserts `//`
// - kbd:[Enter] inside `//!` doc comments automatically inserts `//!`
// - kbd:[Enter] after `{` indents contents and closing `}` of single-line block
// - <kbd>Enter</kbd> inside triple-slash comments automatically inserts `///`
// - <kbd>Enter</kbd> in the middle or after a trailing space in `//` inserts `//`
// - <kbd>Enter</kbd> inside `//!` doc comments automatically inserts `//!`
// - <kbd>Enter</kbd> after `{` indents contents and closing `}` of single-line block
//
// This action needs to be assigned to shortcut explicitly.
//
@ -29,29 +29,27 @@ use ide_db::text_edit::TextEdit;
// Similarly, if rust-analyzer crashes or stops responding, `Enter` might not work.
// In that case, you can still press `Shift-Enter` to insert a newline.
//
// VS Code::
// #### VS Code
//
// Add the following to `keybindings.json`:
// [source,json]
// ----
// ```json
// {
// "key": "Enter",
// "command": "rust-analyzer.onEnter",
// "when": "editorTextFocus && !suggestWidgetVisible && editorLangId == rust"
// }
// ----
// ````
//
// When using the Vim plugin:
// [source,json]
// ----
// ```json
// {
// "key": "Enter",
// "command": "rust-analyzer.onEnter",
// "when": "editorTextFocus && !suggestWidgetVisible && editorLangId == rust && vim.mode == 'Insert'"
// }
// ----
// ````
//
// image::https://user-images.githubusercontent.com/48062697/113065578-04c21800-91b1-11eb-82b8-22b8c481e645.gif[]
// ![On Enter](https://user-images.githubusercontent.com/48062697/113065578-04c21800-91b1-11eb-82b8-22b8c481e645.gif)
pub(crate) fn on_enter(db: &RootDatabase, position: FilePosition) -> Option<TextEdit> {
let parse = db.parse(EditionedFileId::current_edition(position.file_id));
let file = parse.tree();

8
crates/ide/src/view_crate_graph.rs
View file

@ -12,11 +12,9 @@ use triomphe::Arc;
//
// Only workspace crates are included, no crates.io dependencies or sysroot crates.
//
// |===
// | Editor | Action Name
//
// | VS Code | **rust-analyzer: View Crate Graph**
// |===
// | Editor | Action Name |
// |---------|-------------|
// | VS Code | **rust-analyzer: View Crate Graph** |
pub(crate) fn view_crate_graph(db: &RootDatabase, full: bool) -> Result<String, String> {
let crate_graph = db.crate_graph();
let crates_to_render = crate_graph

9
crates/ide/src/view_hir.rs
View file

@ -4,12 +4,11 @@ use syntax::{algo::ancestors_at_offset, ast, AstNode};
// Feature: View Hir
//
// |===
// | Editor | Action Name
//
// | Editor | Action Name |
// |---------|--------------|
// | VS Code | **rust-analyzer: View Hir**
// |===
// image::https://user-images.githubusercontent.com/48062697/113065588-068bdb80-91b1-11eb-9a78-0b4ef1e972fb.gif[]
//
// ![View Hir](https://user-images.githubusercontent.com/48062697/113065588-068bdb80-91b1-11eb-9a78-0b4ef1e972fb.gif)
pub(crate) fn view_hir(db: &RootDatabase, position: FilePosition) -> String {
body_hir(db, position).unwrap_or_else(|| "Not inside a function body".to_owned())
}

8
crates/ide/src/view_item_tree.rs
View file

@ -6,11 +6,9 @@ use span::EditionedFileId;
//
// Displays the ItemTree of the currently open file, for debugging.
//
// |===
// | Editor | Action Name
//
// | VS Code | **rust-analyzer: Debug ItemTree**
// |===
// | Editor | Action Name |
// |---------|-------------|
// | VS Code | **rust-analyzer: Debug ItemTree** |
pub(crate) fn view_item_tree(db: &RootDatabase, file_id: FileId) -> String {
let sema = Semantics::new(db);
let file_id = sema

8
crates/ide/src/view_memory_layout.rs
View file

@ -75,11 +75,9 @@ impl FieldOrTupleIdx {
//
// Displays the recursive memory layout of a datatype.
//
// |===
// | Editor | Action Name
//
// | VS Code | **rust-analyzer: View Memory Layout**
// |===
// | Editor | Action Name |
// |---------|-------------|
// | VS Code | **rust-analyzer: View Memory Layout** |
pub(crate) fn view_memory_layout(
db: &RootDatabase,
position: FilePosition,

6
crates/ide/src/view_mir.rs
View file

@ -4,11 +4,9 @@ use syntax::{algo::ancestors_at_offset, ast, AstNode};
// Feature: View Mir
//
// |===
// | Editor | Action Name
//
// | Editor | Action Name |
// |---------|-------------|
// | VS Code | **rust-analyzer: View Mir**
// |===
pub(crate) fn view_mir(db: &RootDatabase, position: FilePosition) -> String {
body_mir(db, position).unwrap_or_else(|| "Not inside a function body".to_owned())
}

8
crates/ide/src/view_syntax_tree.rs
View file

@ -11,11 +11,9 @@ use syntax::{
//
// Shows a tree view with the syntax tree of the current file
//
// |===
// | Editor | Panel Name
//
// | VS Code | **Rust Syntax Tree**
// |===
// | Editor | Panel Name |
// |---------|-------------|
// | VS Code | **Rust Syntax Tree** |
pub(crate) fn view_syntax_tree(db: &RootDatabase, file_id: FileId) -> String {
let sema = Semantics::new(db);
let parse = sema.parse_guess_edition(file_id);

2
crates/parser/src/syntax_kind/generated.rs
View file

@ -1,4 +1,4 @@
//! Generated by `cargo codegen grammar`, do not edit by hand.
//! Generated by `cargo xtask codegen grammar`, do not edit by hand.
#![allow(bad_style, missing_docs, unreachable_pub)]
use crate::Edition;

20
crates/rust-analyzer/src/config.rs
View file

@ -528,7 +528,7 @@ config_data! {
imports_granularity_enforce: bool = false,
/// How imports should be grouped into use statements.
imports_granularity_group: ImportGranularityDef = ImportGranularityDef::Crate,
/// Group inserted imports by the https://rust-analyzer.github.io/manual.html#auto-import[following order]. Groups are separated by newlines.
/// Group inserted imports by the [following order](https://rust-analyzer.github.io/manual.html#auto-import). Groups are separated by newlines.
imports_group_enable: bool = true,
/// Whether to allow import insertion to merge new imports into single path glob imports like `use std::fmt::*;`.
imports_merge_glob: bool = true,
@ -3624,21 +3624,9 @@ fn manual(fields: &[SchemaField]) -> String {
let name = format!("rust-analyzer.{}", field.replace('_', "."));
let doc = doc_comment_to_string(doc);
if default.contains('\n') {
format_to_acc!(
acc,
r#"[[{name}]]{name}::
+
--
Default:
----
{default}
----
{doc}
--
"#
)
format_to_acc!(acc, " **{name}**\n\nDefault:\n\n```{default}\n\n```\n\n {doc}\n\n ")
} else {
format_to_acc!(acc, "[[{name}]]{name} (default: `{default}`)::\n+\n--\n{doc}--\n")
format_to_acc!(acc, "**{name}** (default: {default})\n\n {doc}\n\n")
}
})
}
@ -3716,7 +3704,7 @@ mod tests {
#[test]
fn generate_config_documentation() {
let docs_path = project_root().join("docs/user/generated_config.adoc");
let docs_path = project_root().join("docs/book/src/configuration_generated.md");
let expected = FullConfigInput::manual();
ensure_file_contents(docs_path.as_std_path(), &expected);
}

2
crates/syntax/src/ast/generated/nodes.rs
View file

@ -1,4 +1,4 @@
//! Generated by `cargo codegen grammar`, do not edit by hand.
//! Generated by `cargo xtask codegen grammar`, do not edit by hand.
#![allow(non_snake_case)]
use crate::{

2
crates/syntax/src/ast/generated/tokens.rs
View file

@ -1,4 +1,4 @@
//! Generated by `cargo codegen grammar`, do not edit by hand.
//! Generated by `cargo xtask codegen grammar`, do not edit by hand.
use crate::{
ast::AstToken,

29
docs/book/README.md Normal file
View file

@ -0,0 +1,29 @@
# rust-analyzer documentation
The rust analyzer manual uses [mdbook](https://rust-lang.github.io/mdBook/).
## Quick start
To run the documentation site locally:
```shell
cargo install mdbook
cd docs/book
mdbook serve
# make changes to documentation files in doc/book/src
# ...
```
mdbook will rebuild the documentation as changes are made.
## Making updates
While not required, installing the mdbook binary can be helfpul in order to see the changes.
Start with the mdbook [User Guide](https://rust-lang.github.io/mdBook/guide/installation.html) to familiarize yourself with the tool.
## Generated documentation
Four sections are generated dynamically: assists, configuration, diagnostics and features. Their content is found in the `generated.md` files
of the respective book section, for example `src/configuration_generated.md`, and are included in the book via mdbook's
[include](https://rust-lang.github.io/mdBook/format/mdbook.html#including-files) functionality. Generated files can be rebuilt by running the various
test cases that generate them, or by simply running all of the `rust-analyzer` tests with `cargo test`.

41
docs/book/book.toml Normal file
View file

@ -0,0 +1,41 @@
[book]
authors = ["The rust-analyzer authors"]
language = "en"
multilingual = false
src = "src"
title = "rust-analyzer"
[rust]
edition = "2021"
[output.html]
edit-url-template = "https://github.com/rust-lang/rust-analyzer/edit/master/manual/{path}"
git-repository-url = "https://github.com/rust-lang/rust-analyzer/tree/master/manual"
mathjax-support = true
site-url = "/manual/"
[output.html.playground]
editable = true
runnable = false
line-numbers = true
[output.html.search]
boost-hierarchy = 2
boost-paragraph = 1
boost-title = 2
expand = true
heading-split-level = 2
limit-results = 20
use-boolean-and = true
[output.html.redirect]
"/manual.html" = "/index.html"
[output.html.fold]
enable = true
level = 3
[preprocessor.toc]
command = "mdbook-toc"
renderer = ["html"]
max-level = 3

21
docs/book/src/README.md Normal file
View file

@ -0,0 +1,21 @@
# rust-analyzer
At its core, rust-analyzer is a **library** for semantic analysis of
Rust code as it changes over time. This manual focuses on a specific
usage of the library -- running it as part of a server that implements
the [Language Server
Protocol](https://microsoft.github.io/language-server-protocol/) (LSP).
The 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.
To improve this document, send a pull request:
[https://github.com/rust-lang/rust-analyzer](https://github.com/rust-lang/rust-analyzer/blob/docs/book/README.md)
The manual is written in markdown and includes
some extra files which are generated from the source code. Run
`cargo test` and `cargo xtask codegen` to create these.
If you have questions about using rust-analyzer, please ask them in the
["IDEs and Editors"](https://users.rust-lang.org/c/ide/14) topic of Rust
users forum.

13
docs/book/src/SUMMARY.md Normal file
View file

@ -0,0 +1,13 @@
# Summary
- [Introduction](README.md)
- [Installation](installation.md)
- [Troubleshooting](troubleshooting.md)
- [Configuration](configuration.md)
- [Non-Cargo Based Projects](non_cargo_based_projects.md)
- [Security](security.md)
- [Privacy](privacy.md)
- [Features](features.md)
- [Assists (Code Actions)](assists.md)
- [Diagnostics](diagnostics.md)
- [Editor Features](editor_features.md)

8
docs/book/src/assists.md Normal file
View file

@ -0,0 +1,8 @@
# Assists
Assists, or code actions, are small local refactorings, available in a
particular context. They are usually triggered by a shortcut or by
clicking a light bulb icon in the editor. Cursor position or selection
is signified by `┃` character.
{{#include assists_generated.md:2:}}

51
docs/book/src/configuration.md Normal file
View file

@ -0,0 +1,51 @@
# Configuration
**Source:**
[config.rs](https://github.com/rust-lang/rust-analyzer/blob/master/crates/rust-analyzer/src/config.rs)
The [Installation](#_installation) section contains details on
configuration for some of the editors. In general `rust-analyzer` is
configured via LSP messages, which means that it’s up to the editor to
decide on the exact format and location of configuration files.
Some clients, such as [VS Code](#vs-code) or [COC plugin in
Vim](#coc-rust-analyzer) provide `rust-analyzer` specific configuration
UIs. Others may require you to know a bit more about the interaction
with `rust-analyzer`.
For the later category, it might help to know that the initial
configuration is specified as a value of the `initializationOptions`
field of the [`InitializeParams` message, in the LSP
protocol](https://microsoft.github.io/language-server-protocol/specifications/specification-current/#initialize).
The spec says that the field type is `any?`, but `rust-analyzer` is
looking for a JSON object that is constructed using settings from the
list below. Name of the setting, ignoring the `rust-analyzer.` prefix,
is used as a path, and value of the setting becomes the JSON property
value.
For example, a very common configuration is to enable proc-macro
support, can be achieved by sending this JSON:
{
"cargo": {
"buildScripts": {
"enable": true,
},
},
"procMacro": {
"enable": true,
}
}
Please consult your editor’s documentation to learn more about how to
configure [LSP
servers](https://microsoft.github.io/language-server-protocol/).
To verify which configuration is actually used by `rust-analyzer`, set
`RA_LOG` environment variable to `rust_analyzer=info` and look for
config-related messages. Logs should show both the JSON that
`rust-analyzer` sees as well as the updated config.
This is the list of config options `rust-analyzer` supports:
{{#include configuration_generated.md}}

1201
docs/book/src/configuration_generated.md Normal file
View file

File diff suppressed because it is too large Load diff

16
docs/book/src/diagnostics.md Normal file
View file

@ -0,0 +1,16 @@
# Diagnostics
While most errors and warnings provided by rust-analyzer come from the
`cargo check` integration, there’s a growing number of diagnostics
implemented using rust-analyzer’s own analysis. Some of these
diagnostics don’t respect `#[allow]` or `#[deny]` attributes yet, but
can be turned off using the `rust-analyzer.diagnostics.enable`,
`rust-analyzer.diagnostics.experimental.enable` or
`rust-analyzer.diagnostics.disabled` settings.
## Clippy
To run `cargo clippy` instead of `cargo check`, you can set
`"rust-analyzer.check.command": "clippy"`.
{{#include diagnostics_generated.md:2:}}

204
docs/book/src/editor_features.md Normal file
View file

@ -0,0 +1,204 @@
# Editor Features
## VS Code
### Color configurations
It is possible to change the foreground/background color and font
family/size of inlay hints. Just add this to your `settings.json`:
```json
{
"editor.inlayHints.fontFamily": "Courier New",
"editor.inlayHints.fontSize": 11,
"workbench.colorCustomizations": {
// Name of the theme you are currently using
"[Default Dark+]": {
"editorInlayHint.foreground": "#868686f0",
"editorInlayHint.background": "#3d3d3d48",
// Overrides for specific kinds of inlay hints
"editorInlayHint.typeForeground": "#fdb6fdf0",
"editorInlayHint.parameterForeground": "#fdb6fdf0",
}
}
}
```
### Semantic style customizations
You can customize the look of different semantic elements in the source
code. For example, mutable bindings are underlined by default and you
can override this behavior by adding the following section to your
`settings.json`:
```json
{
"editor.semanticTokenColorCustomizations": {
"rules": {
"*.mutable": {
"fontStyle": "", // underline is the default
},
}
},
}
```
Most themes doesn’t support styling unsafe operations differently yet.
You can fix this by adding overrides for the rules `operator.unsafe`,
`function.unsafe`, and `method.unsafe`:
```json
{
"editor.semanticTokenColorCustomizations": {
"rules": {
"operator.unsafe": "#ff6600",
"function.unsafe": "#ff6600",
"method.unsafe": "#ff6600"
}
},
}
```
In addition to the top-level rules you can specify overrides for
specific themes. For example, if you wanted to use a darker text color
on a specific light theme, you might write:
```json
{
"editor.semanticTokenColorCustomizations": {
"rules": {
"operator.unsafe": "#ff6600"
},
"[Ayu Light]": {
"rules": {
"operator.unsafe": "#572300"
}
}
},
}
```
Make sure you include the brackets around the theme name. For example,
use `"[Ayu Light]"` to customize the theme Ayu Light.
### Special `when` clause context for keybindings.
You may use `inRustProject` context to configure keybindings for rust
projects only. For example:
```json
{
"key": "ctrl+alt+d",
"command": "rust-analyzer.openDocs",
"when": "inRustProject"
}
```
More about `when` clause contexts
[here](https://code.visualstudio.com/docs/getstarted/keybindings#_when-clause-contexts).
### Setting runnable environment variables
You can use "rust-analyzer.runnables.extraEnv" setting to define
runnable environment-specific substitution variables. The simplest way
for all runnables in a bunch:
```json
"rust-analyzer.runnables.extraEnv": {
"RUN_SLOW_TESTS": "1"
}
```
Or it is possible to specify vars more granularly:
```json
"rust-analyzer.runnables.extraEnv": [
{
// "mask": null, // null mask means that this rule will be applied for all runnables
env: {
"APP_ID": "1",
"APP_DATA": "asdf"
}
},
{
"mask": "test_name",
"env": {
"APP_ID": "2", // overwrites only APP_ID
}
}
]
```
You can use any valid regular expression as a mask. Also note that a
full runnable name is something like **run bin\_or\_example\_name**,
**test some::mod::test\_name** or **test-mod some::mod**, so it is
possible to distinguish binaries, single tests, and test modules with
this masks: `"^run"`, `"^test "` (the trailing space matters!), and
`"^test-mod"` respectively.
If needed, you can set different values for different platforms:
```json
"rust-analyzer.runnables.extraEnv": [
{
"platform": "win32", // windows only
env: {
"APP_DATA": "windows specific data"
}
},
{
"platform": ["linux"],
"env": {
"APP_DATA": "linux data",
}
},
{ // for all platforms
"env": {
"APP_COMMON_DATA": "xxx",
}
}
]
```
### Compiler feedback from external commands
Instead of relying on the built-in `cargo check`, you can configure Code
to run a command in the background and use the `$rustc-watch` problem
matcher to generate inline error markers from its output.
To do this you need to create a new [VS Code
Task](https://code.visualstudio.com/docs/editor/tasks) and set
`"rust-analyzer.checkOnSave": false` in preferences.
For example, if you want to run
[`cargo watch`](https://crates.io/crates/cargo-watch) instead, you might
add the following to `.vscode/tasks.json`:
```json
{
"label": "Watch",
"group": "build",
"type": "shell",
"command": "cargo watch",
"problemMatcher": "$rustc-watch",
"isBackground": true
}
```
### Live Share
VS Code Live Share has partial support for rust-analyzer.
Live Share *requires* the official Microsoft build of VS Code, OSS
builds will not work correctly.
The host’s rust-analyzer instance will be shared with all guests joining
the session. The guests do not have to have the rust-analyzer extension
installed for this to work.
If you are joining a Live Share session and *do* have rust-analyzer
installed locally, commands from the command palette will not work
correctly since they will attempt to communicate with the local server.

3
docs/book/src/features.md Normal file
View file

@ -0,0 +1,3 @@
# Features
{{#include features_generated.md:2:}}

644
docs/book/src/installation.md Normal file
View file

@ -0,0 +1,644 @@
# Installation
In theory, one should be able to just install the [`rust-analyzer`
binary](#rust-analyzer-language-server-binary) and have it automatically
work with any editor. We are not there yet, so some editor specific
setup is required.
Additionally, rust-analyzer needs the sources of the standard library.
If the source code is not present, rust-analyzer will attempt to install
it automatically.
To add the sources manually, run the following command:
$ rustup component add rust-src
## Toolchain
Only the latest stable standard library source is officially supported
for use with rust-analyzer. If you are using an older toolchain or have
an override set, rust-analyzer may fail to understand the Rust source.
You will either need to update your toolchain or use an older version of
rust-analyzer that is compatible with your toolchain.
If you are using an override in your project, you can still force
rust-analyzer to use the stable toolchain via the environment variable
`RUSTUP_TOOLCHAIN`. For example, with VS Code or coc-rust-analyzer:
{ "rust-analyzer.server.extraEnv": { "RUSTUP_TOOLCHAIN": "stable" } }
## VS Code
This is the best supported editor at the moment. The rust-analyzer
plugin for VS Code is maintained [in
tree](https://github.com/rust-lang/rust-analyzer/tree/master/editors/code).
You can install the latest release of the plugin from [the
marketplace](https://marketplace.visualstudio.com/items?itemName=rust-lang.rust-analyzer).
Note that the plugin may cause conflicts with the [previous official
Rust
plugin](https://marketplace.visualstudio.com/items?itemName=rust-lang.rust).
The latter is no longer maintained and should be uninstalled.
The server binary is stored in the extension install directory, which
starts with `rust-lang.rust-analyzer-` and is located under:
- Linux: `~/.vscode/extensions`
- Linux (Remote, such as WSL): `~/.vscode-server/extensions`
- macOS: `~/.vscode/extensions`
- Windows: `%USERPROFILE%\.vscode\extensions`
As an exception, on NixOS, the extension makes a copy of the server and
stores it under
`~/.config/Code/User/globalStorage/rust-lang.rust-analyzer`.
Note that we only support the two most recent versions of VS Code.
### Updates
The 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.
#### Nightly
We ship nightly releases for VS Code. To help us out by testing the
newest code, you can enable pre-release versions in the Code extension
page.
### Manual installation
Alternatively, download a VSIX corresponding to your platform from the
[releases](https://github.com/rust-lang/rust-analyzer/releases) page.
Install the extension with the `Extensions: Install from VSIX` command
within VS Code, or from the command line via:
$ code --install-extension /path/to/rust-analyzer.vsix
If you are running an unsupported platform, you can install
`rust-analyzer-no-server.vsix` and compile or obtain a server binary.
Copy the server anywhere, then add the path to your settings.json, for
example:
{ "rust-analyzer.server.path": "~/.local/bin/rust-analyzer-linux" }
### Building From Source
Both the server and the Code plugin can be installed from source:
$ git clone https://github.com/rust-lang/rust-analyzer.git && cd rust-analyzer
$ cargo xtask install
You’ll need Cargo, nodejs (matching a supported version of VS Code) and
npm for this.
Note that installing via `xtask install` does not work for VS Code
Remote, instead you’ll need to install the `.vsix` manually.
If you’re not using Code, you can compile and install only the LSP
server:
$ cargo xtask install --server
Make sure that `.cargo/bin` is in `$PATH` and precedes paths where
`rust-analyzer` may also be installed. Specifically, `rustup` includes a
proxy called `rust-analyzer`, which can cause problems if you’re
planning to use a source build or even a downloaded binary.
## rust-analyzer Language Server Binary
Other editors generally require the `rust-analyzer` binary to be in
`$PATH`. You can download pre-built binaries from the
[releases](https://github.com/rust-lang/rust-analyzer/releases) page.
You will need to uncompress and rename the binary for your platform,
e.g. from `rust-analyzer-aarch64-apple-darwin.gz` on Mac OS to
`rust-analyzer`, make it executable, then move it into a directory in
your `$PATH`.
On Linux to install the `rust-analyzer` binary into `~/.local/bin`,
these commands should work:
$ mkdir -p ~/.local/bin
$ curl -L https://github.com/rust-lang/rust-analyzer/releases/latest/download/rust-analyzer-x86_64-unknown-linux-gnu.gz | gunzip -c - > ~/.local/bin/rust-analyzer
$ chmod +x ~/.local/bin/rust-analyzer
Make sure that `~/.local/bin` is listed in the `$PATH` variable and use
the appropriate URL if you’re not on a `x86-64` system.
You don’t have to use `~/.local/bin`, any other path like `~/.cargo/bin`
or `/usr/local/bin` will work just as well.
Alternatively, you can install it from source using the command below.
You’ll need the latest stable version of the Rust toolchain.
$ git clone https://github.com/rust-lang/rust-analyzer.git && cd rust-analyzer
$ cargo xtask install --server
If 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 [this
issue](https://github.com/rust-lang/rust-analyzer/issues/1811). On Unix,
running the editor from a shell or changing the `.desktop` file to set
the environment should help.
### rustup
`rust-analyzer` is available in `rustup`:
$ rustup component add rust-analyzer
### Arch Linux
The `rust-analyzer` binary can be installed from the repos or AUR (Arch
User Repository):
- [`rust-analyzer`](https://www.archlinux.org/packages/extra/x86_64/rust-analyzer/)
(built from latest tagged source)
- [`rust-analyzer-git`](https://aur.archlinux.org/packages/rust-analyzer-git)
(latest Git version)
Install it with pacman, for example:
$ pacman -S rust-analyzer
### Gentoo Linux
`rust-analyzer` is installed when the `rust-analyzer` use flag is set for dev-lang/rust or dev-lang/rust-bin. You also need to set the `rust-src` use flag.
### macOS
The `rust-analyzer` binary can be installed via
[Homebrew](https://brew.sh/).
$ brew install rust-analyzer
### Windows
It is recommended to install the latest Microsoft Visual C++ Redistributable prior to installation.
Download links can be found
[here](https://learn.microsoft.com/en-us/cpp/windows/latest-supported-vc-redist).
## VS Code or VSCodium in Flatpak
Setting up `rust-analyzer` with a Flatpak version of Code is not trivial
because of the Flatpak sandbox. While the sandbox can be disabled for
some directories, `/usr/bin` will always be mounted under
`/run/host/usr/bin`. This prevents access to the system’s C compiler, a
system-wide installation of Rust, or any other libraries you might want
to link to. Some compilers and libraries can be acquired as Flatpak
SDKs, such as `org.freedesktop.Sdk.Extension.rust-stable` or
`org.freedesktop.Sdk.Extension.llvm15`.
If you use a Flatpak SDK for Rust, it must be in your `PATH`:
* install the SDK extensions with `flatpak install org.freedesktop.Sdk.Extension.{llvm15,rust-stable}//23.08`
* enable SDK extensions in the editor with the environment variable `FLATPAK_ENABLE_SDK_EXT=llvm15,rust-stable` (this can be done using flatseal or `flatpak override`)
If you want to use Flatpak in combination with `rustup`, the following
steps might help:
- both Rust and `rustup` have to be installed using
<https://rustup.rs>. Distro packages *will not* work.
- you need to launch Code, open a terminal and run `echo $PATH`
- using
[Flatseal](https://flathub.org/apps/details/com.github.tchx84.Flatseal),
you must add an environment variable called `PATH`. Set its value to
the output from above, appending `:~/.cargo/bin`, where `~` is the
path to your home directory. You must replace `~`, as it won’t be
expanded otherwise.
- while Flatseal is open, you must enable access to "All user files"
A C compiler should already be available via `org.freedesktop.Sdk`. Any
other tools or libraries you will need to acquire from Flatpak.
## Emacs
Prerequisites: You have installed the [`rust-analyzer`
binary](#rust-analyzer-language-server-binary).
To use `rust-analyzer`, you need to install and enable one of the two
popular LSP client implementations for Emacs,
[Eglot](https://github.com/joaotavora/eglot) or [LSP
Mode](https://github.com/emacs-lsp/lsp-mode). Both enable
`rust-analyzer` by default in rust buffers if it is available.
### Eglot
Eglot is the more minimalistic and lightweight LSP client for Emacs,
integrates well with existing Emacs functionality and is built into
Emacs starting from release 29.
After installing Eglot, e.g. via `M-x package-install` (not needed from
Emacs 29), you can enable it via the `M-x eglot` command or load it
automatically in `rust-mode` via
(add-hook 'rust-mode-hook 'eglot-ensure)
To enable clippy, you will need to configure the initialization options
to pass the `check.command` setting.
(add-to-list 'eglot-server-programs
'((rust-ts-mode rust-mode) .
("rust-analyzer" :initializationOptions (:check (:command "clippy")))))
For more detailed instructions and options see the [Eglot
manual](https://joaotavora.github.io/eglot) (also available from Emacs
via `M-x info`) and the [Eglot
readme](https://github.com/joaotavora/eglot/blob/master/README.md).
Eglot does not support the rust-analyzer extensions to the
language-server protocol and does not aim to do so in the future. The
[eglot-x](https://github.com/nemethf/eglot-x#rust-analyzer-extensions)
package adds experimental support for those LSP extensions.
### LSP Mode
LSP-mode is the original LSP-client for emacs. Compared to Eglot it has
a larger codebase and supports more features, like LSP protocol
extensions. With extension packages like [LSP
UI](https://github.com/emacs-lsp/lsp-mode) it offers a lot of visual
eyecandy. Further it integrates well with [DAP
mode](https://github.com/emacs-lsp/dap-mode) for support of the Debug
Adapter Protocol.
You can install LSP-mode via `M-x package-install` and then run it via
the `M-x lsp` command or load it automatically in rust buffers with
(add-hook 'rust-mode-hook 'lsp-deferred)
For more information on how to set up LSP mode and its extension package
see the instructions in the [LSP mode
manual](https://emacs-lsp.github.io/lsp-mode/page/installation). Also
see the [rust-analyzer
section](https://emacs-lsp.github.io/lsp-mode/page/lsp-rust-analyzer/)
for `rust-analyzer` specific options and commands, which you can
optionally bind to keys.
Note the excellent
[guide](https://robert.kra.hn/posts/2021-02-07_rust-with-emacs/) from
[@rksm](https://github.com/rksm) on how to set-up Emacs for Rust
development with LSP mode and several other packages.
## Vim/Neovim
Prerequisites: You have installed the [`rust-analyzer`
binary](#rust-analyzer-language-server-binary). Not needed if the
extension can install/update it on its own, coc-rust-analyzer is one
example.
There are several LSP client implementations for Vim or Neovim:
### coc-rust-analyzer
1. Install coc.nvim by following the instructions at
[coc.nvim](https://github.com/neoclide/coc.nvim) (Node.js required)
2. Run `:CocInstall coc-rust-analyzer` to install
[coc-rust-analyzer](https://github.com/fannheyward/coc-rust-analyzer),
this extension implements *most* of the features supported in the
VSCode extension:
- automatically install and upgrade stable/nightly releases
- same configurations as VSCode extension,
`rust-analyzer.server.path`, `rust-analyzer.cargo.features` etc.
- same commands too, `rust-analyzer.analyzerStatus`,
`rust-analyzer.ssr` etc.
- inlay hints for variables and method chaining, *Neovim Only*
Note: for code actions, use `coc-codeaction-cursor` and
`coc-codeaction-selected`; `coc-codeaction` and `coc-codeaction-line`
are unlikely to be useful.
### LanguageClient-neovim
1. Install LanguageClient-neovim by following the instructions
[here](https://github.com/autozimu/LanguageClient-neovim)
- The GitHub project wiki has extra tips on configuration
2. Configure by adding this to your Vim/Neovim config file (replacing
the existing Rust-specific line if it exists):
let g:LanguageClient_serverCommands = {
\ 'rust': ['rust-analyzer'],
\ }
### YouCompleteMe
Install YouCompleteMe by following the instructions
[here](https://github.com/ycm-core/YouCompleteMe#installation).
rust-analyzer is the default in ycm, it should work out of the box.
### ALE
To use the LSP server in [ale](https://github.com/dense-analysis/ale):
let g:ale_linters = {'rust': ['analyzer']}
### nvim-lsp
Neovim 0.5 has built-in language server support. For a quick start
configuration of rust-analyzer, use
[neovim/nvim-lspconfig](https://github.com/neovim/nvim-lspconfig#rust_analyzer).
Once `neovim/nvim-lspconfig` is installed, use
`lua require'lspconfig'.rust_analyzer.setup({})` in your `init.vim`.
You can also pass LSP settings to the server:
lua << EOF
local lspconfig = require'lspconfig'
local on_attach = function(client)
require'completion'.on_attach(client)
end
lspconfig.rust_analyzer.setup({
on_attach = on_attach,
settings = {
["rust-analyzer"] = {
imports = {
granularity = {
group = "module",
},
prefix = "self",
},
cargo = {
buildScripts = {
enable = true,
},
},
procMacro = {
enable = true
},
}
}
})
EOF
If you're running Neovim 0.10 or later, you can enable inlay hints via `on_attach`:
```vim
lspconfig.rust_analyzer.setup({
on_attach = function(client, bufnr)
vim.lsp.inlay_hint.enable(true, { bufnr = bufnr })
end
})
```
Note that the hints are only visible after `rust-analyzer` has finished loading **and** you have to
edit the file to trigger a re-render.
See <https://sharksforarms.dev/posts/neovim-rust/> for more tips on
getting started.
Check out <https://github.com/mrcjkb/rustaceanvim> for a batteries
included rust-analyzer setup for Neovim.
### vim-lsp
vim-lsp is installed by following [the plugin
instructions](https://github.com/prabirshrestha/vim-lsp). It can be as
simple as adding this line to your `.vimrc`:
Plug 'prabirshrestha/vim-lsp'
Next you need to register the `rust-analyzer` binary. If it is avim.lspvailable
in `$PATH`, you may want to add this to your `.vimrc`:
if executable('rust-analyzer')
au User lsp_setup call lsp#register_server({
\ 'name': 'Rust Language Server',
\ 'cmd': {server_info->['rust-analyzer']},
\ 'whitelist': ['rust'],
\ })
endif
There is no dedicated UI for the server configuration, so you would need
to send any options as a value of the `initialization_options` field, as
described in the [Configuration](#configuration) section. Here is an
example of how to enable the proc-macro support:
if executable('rust-analyzer')
au User lsp_setup call lsp#register_server({
\ 'name': 'Rust Language Server',
\ 'cmd': {server_info->['rust-analyzer']},
\ 'whitelist': ['rust'],
\ 'initialization_options': {
\ 'cargo': {
\ 'buildScripts': {
\ 'enable': v:true,
\ },
\ },
\ 'procMacro': {
\ 'enable': v:true,
\ },
\ },
\ })
endif
## Sublime Text
### Sublime Text 4:
- Follow the instructions in
[LSP-rust-analyzer](https://github.com/sublimelsp/LSP-rust-analyzer).
Install
[LSP-file-watcher-chokidar](https://packagecontrol.io/packages/LSP-file-watcher-chokidar)
to enable file watching (`workspace/didChangeWatchedFiles`).
### Sublime Text 3:
- Install the [`rust-analyzer`
binary](#rust-analyzer-language-server-binary).
- Install the [LSP package](https://packagecontrol.io/packages/LSP).
- From the command palette, run `LSP: Enable Language Server Globally`
and select `rust-analyzer`.
If it worked, you should see "rust-analyzer, Line X, Column Y" on the
left side of the status bar, and after waiting a bit, functionalities
like tooltips on hovering over variables should become available.
If you get an error saying `No such file or directory: 'rust-analyzer'`,
see the [`rust-analyzer` binary](#rust-analyzer-language-server-binary)
section on installing the language server binary.
## GNOME Builder
GNOME Builder 3.37.1 and newer has native `rust-analyzer` support. If
the LSP binary is not available, GNOME Builder can install it when
opening a Rust file.
## Eclipse IDE
Support for Rust development in the Eclipse IDE is provided by [Eclipse
Corrosion](https://github.com/eclipse/corrosion). If available in PATH
or in some standard location, `rust-analyzer` is detected and powers
editing of Rust files without further configuration. If `rust-analyzer`
is not detected, Corrosion will prompt you for configuration of your
Rust toolchain and language server with a link to the *Window &gt;
Preferences &gt; Rust* preference page; from here a button allows to
download and configure `rust-analyzer`, but you can also reference
another installation. You’ll need to close and reopen all .rs and Cargo
files, or to restart the IDE, for this change to take effect.
## Kate Text Editor
Support for the language server protocol is built into Kate through the
LSP plugin, which is included by default. It is preconfigured to use
rust-analyzer for Rust sources since Kate 21.12.
To change rust-analyzer config options, start from the following example
and put it into Kate’s "User Server Settings" tab (located under the LSP
Client settings):
{
"servers": {
"rust": {
"initializationOptions": {
"cachePriming": {
"enable": false
},
"check": {
"allTargets": false
},
"checkOnSave": false
}
}
}
}
Then click on apply, and restart the LSP server for your rust project.
## juCi++
[juCi++](https://gitlab.com/cppit/jucipp) has built-in support for the
language server protocol, and since version 1.7.0 offers installation of
both Rust and rust-analyzer when opening a Rust file.
## Kakoune
[Kakoune](https://kakoune.org/) supports LSP with the help of
[`kak-lsp`](https://github.com/kak-lsp/kak-lsp). Follow the
[instructions](https://github.com/kak-lsp/kak-lsp#installation) to
install `kak-lsp`. To configure `kak-lsp`, refer to the [configuration
section](https://github.com/kak-lsp/kak-lsp#configuring-kak-lsp) which
is basically about copying the [configuration
file](https://github.com/kak-lsp/kak-lsp/blob/master/kak-lsp.toml) in
the right place (latest versions should use `rust-analyzer` by default).
Finally, you need to configure Kakoune to talk to `kak-lsp` (see [Usage
section](https://github.com/kak-lsp/kak-lsp#usage)). A basic
configuration will only get you LSP but you can also activate inlay
diagnostics and auto-formatting on save. The following might help you
get all of this.
eval %sh{kak-lsp --kakoune -s $kak_session} # Not needed if you load it with plug.kak.
hook global WinSetOption filetype=rust %{
# Enable LSP
lsp-enable-window
# Auto-formatting on save
hook window BufWritePre .* lsp-formatting-sync
# Configure inlay hints (only on save)
hook window -group rust-inlay-hints BufWritePost .* rust-analyzer-inlay-hints
hook -once -always window WinSetOption filetype=.* %{
remove-hooks window rust-inlay-hints
}
}
## Helix
[Helix](https://docs.helix-editor.com/) supports LSP by default.
However, it won’t install `rust-analyzer` automatically. You can follow
instructions for installing [`rust-analyzer`
binary](#rust-analyzer-language-server-binary).
## Visual Studio 2022
There are multiple rust-analyzer extensions for Visual Studio 2022 on
Windows:
### rust-analyzer.vs
(License: Creative Commons Attribution-NonCommercial-ShareAlike 4.0
International)
[Visual Studio
Marketplace](https://marketplace.visualstudio.com/items?itemName=kitamstudios.RustAnalyzer)
[GitHub](https://github.com/kitamstudios/rust-analyzer/)
Support for Rust development in the Visual Studio IDE is enabled by the
[rust-analyzer](https://marketplace.visualstudio.com/items?itemName=kitamstudios.RustAnalyzer)
package. Either click on the download link or install from IDE’s
extension manager. For now [Visual Studio
2022](https://visualstudio.microsoft.com/downloads/) is required. All
editions are supported viz. Community, Professional & Enterprise. The
package aims to provide 0-friction installation and therefore comes
loaded with most things required including rust-analyzer binary. If
anything it needs is missing, appropriate errors / warnings will guide
the user. E.g. cargo.exe needs to be in path and the package will tell
you as much. This package is under rapid active development. So if you
encounter any issues please file it at
[rust-analyzer.vs](https://github.com/kitamstudios/rust-analyzer/).
### VS\_RustAnalyzer
(License: GPL)
[Visual Studio
Marketplace](https://marketplace.visualstudio.com/items?itemName=cchharris.vsrustanalyzer)
[GitHub](https://github.com/cchharris/VS-RustAnalyzer)
### SourceGear Rust
(License: closed source)
[Visual Studio
Marketplace](https://marketplace.visualstudio.com/items?itemName=SourceGear.SourceGearRust)
[GitHub (docs, issues,
discussions)](https://github.com/sourcegear/rust-vs-extension)
- Free (no-cost)
- Supports all editions of Visual Studio 2022 on Windows: Community,
Professional, or Enterprise
## Lapce
[Lapce](https://lapce.dev/) has a Rust plugin which you can install
directly. Unfortunately, it downloads an old version of `rust-analyzer`,
but you can set the server path under Settings.
## Crates
There is a package named `ra_ap_rust_analyzer` available on
[crates.io](https://crates.io/crates/ra_ap_rust-analyzer), for someone
who wants to use it programmatically.
For more details, see [the publish
workflow](https://github.com/rust-lang/rust-analyzer/blob/master/.github/workflows/autopublish.yaml).
## Zed
[Zed](https://zed.dev) has native `rust-analyzer` support. If the LSP
binary is not available, Zed can install it when opening a Rust file.

246
docs/book/src/non_cargo_based_projects.md Normal file
View file

@ -0,0 +1,246 @@
# Non-Cargo Based Projects
rust-analyzer does not require Cargo. However, if you use some other
build system, you’ll have to describe the structure of your project for
rust-analyzer in the `rust-project.json` format:
```typescript
interface JsonProject {
/// Path to the sysroot directory.
///
/// The sysroot is where rustc looks for the
/// crates that are built-in to rust, such as
/// std.
///
/// https://doc.rust-lang.org/rustc/command-line-arguments.html#--sysroot-override-the-system-root
///
/// To see the current value of sysroot, you
/// can query rustc:
///
/// ```
/// $ rustc --print sysroot
/// /Users/yourname/.rustup/toolchains/stable-x86_64-apple-darwin
/// ```
sysroot?: string;
/// Path to the directory with *source code* of
/// sysroot crates.
///
/// By default, this is `lib/rustlib/src/rust/library`
/// relative to the sysroot.
///
/// It should point to the directory where std,
/// core, and friends can be found:
///
/// https://github.com/rust-lang/rust/tree/master/library.
///
/// If provided, rust-analyzer automatically adds
/// dependencies on sysroot crates. Conversely,
/// if you omit this path, you can specify sysroot
/// dependencies yourself and, for example, have
/// several different "sysroots" in one graph of
/// crates.
sysroot_src?: string;
/// List of groups of common cfg values, to allow
/// sharing them between crates.
///
/// Maps from group name to its cfgs. Cfg follow
/// the same format as `Crate.cfg`.
cfg_groups?: { [key: string]: string[]; };
/// The set of crates comprising the current
/// project. Must include all transitive
/// dependencies as well as sysroot crate (libstd,
/// libcore and such).
crates: Crate[];
/// Configuration for CLI commands.
///
/// These are used for running and debugging binaries
/// and tests without encoding build system-specific
/// knowledge into rust-analyzer.
///
/// # Example
///
/// Below is an example of a test runnable. `{label}` and `{test_id}`
/// are explained in `Runnable::args`'s documentation below.
///
/// ```json
/// {
/// "program": "buck",
/// "args": [
/// "test",
/// "{label}",
/// "--",
/// "{test_id}",
/// "--print-passing-details"
/// ],
/// "cwd": "/home/user/repo-root/",
/// "kind": "testOne"
/// }
/// ```
runnables?: Runnable[];
}
interface Crate {
/// Optional crate name used for display purposes,
/// without affecting semantics. See the `deps`
/// key for semantically-significant crate names.
display_name?: string;
/// Path to the root module of the crate.
root_module: string;
/// Edition of the crate.
edition: '2015' | '2018' | '2021' | '2024';
/// The version of the crate. Used for calculating
/// the correct docs.rs URL.
version?: string;
/// Dependencies
deps: Dep[];
/// Should this crate be treated as a member of
/// current "workspace".
///
/// By default, inferred from the `root_module`
/// (members are the crates which reside inside
/// the directory opened in the editor).
///
/// Set this to `false` for things like standard
/// library and 3rd party crates to enable
/// performance optimizations (rust-analyzer
/// assumes that non-member crates don't change).
is_workspace_member?: boolean;
/// Optionally specify the (super)set of `.rs`
/// files comprising this crate.
///
/// By default, rust-analyzer assumes that only
/// files under `root_module.parent` can belong
/// to a crate. `include_dirs` are included
/// recursively, unless a subdirectory is in
/// `exclude_dirs`.
///
/// Different crates can share the same `source`.
///
/// If two crates share an `.rs` file in common,
/// they *must* have the same `source`.
/// rust-analyzer assumes that files from one
/// source can't refer to files in another source.
source?: {
include_dirs: string[];
exclude_dirs: string[];
};
/// List of cfg groups this crate inherits.
///
/// All cfg in these groups will be concatenated to
/// `cfg`. It is impossible to replace a value from
/// the groups.
cfg_groups?: string[];
/// The set of cfgs activated for a given crate, like
/// `["unix", "feature=\"foo\"", "feature=\"bar\""]`.
cfg: string[];
/// Target tuple for this Crate.
///
/// Used when running `rustc --print cfg`
/// to get target-specific cfgs.
target?: string;
/// Environment variables, used for
/// the `env!` macro
env: { [key: string]: string; };
/// Whether the crate is a proc-macro crate.
is_proc_macro: boolean;
/// For proc-macro crates, path to compiled
/// proc-macro (.so file).
proc_macro_dylib_path?: string;
/// Repository, matching the URL that would be used
/// in Cargo.toml.
repository?: string;
/// Build-specific data about this crate.
build?: BuildInfo;
}
interface Dep {
/// Index of a crate in the `crates` array.
crate: number;
/// Name as should appear in the (implicit)
/// `extern crate name` declaration.
name: string;
}
interface BuildInfo {
/// The name associated with this crate.
///
/// This is determined by the build system that produced
/// the `rust-project.json` in question. For instance, if buck were used,
/// the label might be something like `//ide/rust/rust-analyzer:rust-analyzer`.
///
/// Do not attempt to parse the contents of this string; it is a build system-specific
/// identifier similar to `Crate::display_name`.
label: string;
/// Path corresponding to the build system-specific file defining the crate.
build_file: string;
/// The kind of target.
///
/// This information is used to determine what sort
/// of runnable codelens to provide, if any.
target_kind: 'bin' | 'lib' | 'test';
}
interface Runnable {
/// The program invoked by the runnable.
///
/// For example, this might be `cargo`, `buck`, or `bazel`.
program: string;
/// The arguments passed to `program`.
args: string[];
/// The current working directory of the runnable.
cwd: string;
/// Used to decide what code lens to offer.
///
/// `testOne`: This runnable will be used when the user clicks the 'Run Test'
/// CodeLens above a test.
///
/// The args for testOne can contain two template strings:
/// `{label}` and `{test_id}`. `{label}` will be replaced
/// with the `Build::label` and `{test_id}` will be replaced
/// with the test name.
kind: 'testOne' | string;
}
```
This format is provisional and subject to change. Specifically, the
`roots` setup will be different eventually.
There are three ways to feed `rust-project.json` to rust-analyzer:
- Place `rust-project.json` file at the root of the project, and
rust-analyzer will discover it.
- Specify
`"rust-analyzer.linkedProjects": [ "path/to/rust-project.json" ]` in
the settings (and make sure that your LSP client sends settings as a
part of initialize request).
- Specify
`"rust-analyzer.linkedProjects": [ { "roots": […​], "crates": […​] }]`
inline.
Relative paths are interpreted relative to `rust-project.json` file
location or (for inline JSON) relative to `rootUri`.
You can set the `RA_LOG` environment variable to `rust_analyzer=info` to
inspect how rust-analyzer handles config and project loading.
Note that calls to `cargo check` are disabled when using
`rust-project.json` by default, so compilation errors and warnings will
no longer be sent to your LSP client. To enable these compilation errors
you will need to specify explicitly what command rust-analyzer should
run to perform the checks using the
`rust-analyzer.check.overrideCommand` configuration. As an example, the
following configuration explicitly sets `cargo check` as the `check`
command.
{ "rust-analyzer.check.overrideCommand": ["cargo", "check", "--message-format=json"] }
`check.overrideCommand` requires the command specified to output json
error messages for rust-analyzer to consume. The `--message-format=json`
flag does this for `cargo check` so whichever command you use must also
output errors in this format. See the [Configuration](#_configuration)
section for more information.

15
docs/book/src/privacy.md Normal file
View file

@ -0,0 +1,15 @@
# Privacy
The LSP server performs no network access in itself, but runs
`cargo metadata` which will update or download the crate registry and
the source code of the project dependencies. If enabled (the default),
build scripts and procedural macros can do anything.
The Code extension does not access the network.
Any other editor plugins are not under the control of the
`rust-analyzer` developers. For any privacy concerns, you should check
with their respective developers.
For `rust-analyzer` developers, `cargo xtask release` uses the GitHub
API to put together the release notes.

19
docs/book/src/security.md Normal file
View file

@ -0,0 +1,19 @@
# Security
At the moment, rust-analyzer assumes that all code is trusted. Here is a
**non-exhaustive** list of ways to make rust-analyzer execute arbitrary
code:
- proc macros and build scripts are executed by default
- `.cargo/config` can override `rustc` with an arbitrary executable
- `rust-toolchain.toml` can override `rustc` with an arbitrary
executable
- VS Code plugin reads configuration from project directory, and that
can be used to override paths to various executables, like `rustfmt`
or `rust-analyzer` itself.
- rust-analyzer’s syntax trees library uses a lot of `unsafe` and
hasn’t been properly audited for memory safety.

50
docs/book/src/troubleshooting.md Normal file
View file

@ -0,0 +1,50 @@
# Troubleshooting
Start with looking at the rust-analyzer version. Try **rust-analyzer:
Show RA Version** in VS Code (using **Command Palette** feature
typically activated by Ctrl+Shift+P) or `rust-analyzer --version` in the
command line. If the date is more than a week ago, it’s better to update
rust-analyzer version.
The next thing to check would be panic messages in rust-analyzer’s log.
Log messages are printed to stderr, in VS Code you can see them in the
`Output > Rust Analyzer Language Server` tab of the panel. To see more
logs, set the `RA_LOG=info` environment variable, this can be done
either by setting the environment variable manually or by using
`rust-analyzer.server.extraEnv`, note that both of these approaches
require the server to be restarted.
To fully capture LSP messages between the editor and the server, run
the `rust-analyzer: Toggle LSP Logs` command and check `Output > Rust
Analyzer Language Server Trace`.
The root cause for many "nothing works" problems is that rust-analyzer
fails to understand the project structure. To debug that, first note the
`rust-analyzer` section in the status bar. If it has an error icon and
red, that’s the problem (hover will have somewhat helpful error
message). **rust-analyzer: Status** prints dependency information for
the current file. Finally, `RA_LOG=project_model=debug` enables verbose
logs during project loading.
If rust-analyzer outright crashes, try running
`rust-analyzer analysis-stats /path/to/project/directory/` on the
command line. This command type checks the whole project in batch mode
bypassing LSP machinery.
When filing issues, it is useful (but not necessary) to try to minimize
examples. An ideal bug reproduction looks like this:
```shell
$ git clone https://github.com/username/repo.git && cd repo && git switch --detach commit-hash
$ rust-analyzer --version
rust-analyzer dd12184e4 2021-05-08 dev
$ rust-analyzer analysis-stats .
💀 💀 💀
```
It is especially useful when the `repo` doesn’t use external crates or
the standard library.
If you want to go as far as to modify the source code to debug the
problem, be sure to take a look at the [dev
docs](https://github.com/rust-lang/rust-analyzer/tree/master/docs/dev)!

4
docs/dev/style.md
View file

@ -873,7 +873,7 @@ Use `anyhow::format_err!` rather than `anyhow::anyhow`.
**Rationale:** consistent, boring, avoids stuttering.
There's no specific guidance on the formatting of error messages, see [anyhow/#209](https://github.com/dtolnay/anyhow/issues/209).
Do not end error and context messages with `.` though.
Do not end error and context messages with `.` though.
## Early Returns
@ -1172,7 +1172,7 @@ MergeBehavior::Last => {
**Rationale:** writing a sentence (or maybe even a paragraph) rather just "a comment" creates a more appropriate frame of mind.
It tricks you into writing down more of the context you keep in your head while coding.
For `.md` and `.adoc` files, prefer a sentence-per-line format, don't wrap lines.
For `.md` files prefer a sentence-per-line format, don't wrap lines.
If the line is too long, you want to split the sentence in two :-)
**Rationale:** much easier to edit the text and read the diff, see [this link](https://asciidoctor.org/docs/asciidoc-recommended-practices/#one-sentence-per-line).

1
docs/user/.gitignore vendored
View file

@ -1 +0,0 @@
manual.html

1197
docs/user/generated_config.adoc
View file

File diff suppressed because it is too large Load diff

1121
docs/user/manual.adoc
View file

File diff suppressed because it is too large Load diff

13
xtask/src/codegen.rs
View file

@ -24,6 +24,7 @@ impl flags::Codegen {
diagnostics_docs::generate(self.check);
assists_doc_tests::generate(self.check);
parser_inline_tests::generate(self.check);
feature_docs::generate(self.check)
// diagnostics_docs::generate(self.check) doesn't generate any tests
// lints::generate(self.check) Updating clones the rust repo, so don't run it unless
// explicitly asked for
@ -116,13 +117,7 @@ impl fmt::Display for Location {
let path = self.file.strip_prefix(project_root()).unwrap().display().to_string();
let path = path.replace('\\', "/");
let name = self.file.file_name().unwrap();
write!(
f,
"https://github.com/rust-lang/rust-analyzer/blob/master/{}#L{}[{}]",
path,
self.line,
name.to_str().unwrap()
)
write!(f, " [{}]({}#{}) ", name.to_str().unwrap(), path, self.line)
}
}
@ -162,7 +157,7 @@ fn reformat(text: String) -> String {
}
fn add_preamble(cg: CodegenType, mut text: String) -> String {
let preamble = format!("//! Generated by `cargo codegen {cg}`, do not edit by hand.\n\n");
let preamble = format!("//! Generated by `cargo xtask codegen {cg}`, do not edit by hand.\n\n");
text.insert_str(0, &preamble);
text
}
@ -186,7 +181,7 @@ fn ensure_file_contents(cg: CodegenType, file: &Path, contents: &str, check: boo
file.display(),
if std::env::var("CI").is_ok() {
format!(
"\n NOTE: run `cargo codegen {cg}` locally and commit the updated files\n"
"\n NOTE: run `cargo xtask codegen {cg}` locally and commit the updated files\n"
)
} else {
"".to_owned()

10
xtask/src/codegen/assists_doc_tests.rs
View file

@ -1,4 +1,4 @@
//! Generates `assists.md` documentation.
//! Generates `assists_generated.md` documentation.
use std::{fmt, fs, path::Path};
@ -62,7 +62,7 @@ r#####"
crate::flags::CodegenType::AssistsDocTests,
assists.into_iter().map(|it| it.to_string()).collect::<Vec<_>>().join("\n\n"),
);
let dst = project_root().join("docs/user/generated_assists.adoc");
let dst = project_root().join("docs/book/src/assists_generated.md");
fs::write(dst, contents).unwrap();
}
}
@ -146,7 +146,7 @@ impl fmt::Display for Assist {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
let _ = writeln!(
f,
"[discrete]\n=== `{}`
"### `{}`
**Source:** {}",
self.id, self.location,
);
@ -159,11 +159,11 @@ impl fmt::Display for Assist {
"
{}
.Before
#### Before
```rust
{}```
.After
#### After
```rust
{}```",
section.doc,

6
xtask/src/codegen/diagnostics_docs.rs
View file

@ -1,4 +1,4 @@
//! Generates `assists.md` documentation.
//! Generates `diagnostics_generated.md` documentation.
use std::{fmt, fs, io, path::PathBuf};
@ -14,7 +14,7 @@ pub(crate) fn generate(check: bool) {
let contents =
diagnostics.into_iter().map(|it| it.to_string()).collect::<Vec<_>>().join("\n\n");
let contents = add_preamble(crate::flags::CodegenType::DiagnosticsDocs, contents);
let dst = project_root().join("docs/user/generated_diagnostic.adoc");
let dst = project_root().join("docs/book/src/diagnostics_generated.md");
fs::write(dst, contents).unwrap();
}
}
@ -73,6 +73,6 @@ fn is_valid_diagnostic_name(diagnostic: &str) -> Result<(), String> {
impl fmt::Display for Diagnostic {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
writeln!(f, "=== {}\n**Source:** {}\n{}", self.id, self.location, self.doc)
writeln!(f, "#### {}\n\nSource: {}\n\n{}\n\n", self.id, self.location, self.doc)
}
}

16
xtask/src/codegen/feature_docs.rs
View file

@ -1,9 +1,9 @@
//! Generates `assists.md` documentation.
//! Generates `features_generated.md` documentation.
use std::{fmt, fs, io, path::PathBuf};
use crate::{
codegen::{CommentBlock, Location},
codegen::{add_preamble, CommentBlock, Location},
project_root,
util::list_rust_files,
};
@ -11,14 +11,8 @@ use crate::{
pub(crate) fn generate(_check: bool) {
let features = Feature::collect().unwrap();
let contents = features.into_iter().map(|it| it.to_string()).collect::<Vec<_>>().join("\n\n");
let contents = format!(
"
// Generated file, do not edit by hand, see `sourcegen_feature_docs`.
{}
",
contents.trim()
);
let dst = project_root().join("docs/user/generated_features.adoc");
let contents = add_preamble(crate::flags::CodegenType::FeatureDocs, contents);
let dst = project_root().join("docs/book/src/features_generated.md");
fs::write(dst, contents).unwrap();
}
@ -80,6 +74,6 @@ fn is_valid_feature_name(feature: &str) -> Result<(), String> {
impl fmt::Display for Feature {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
writeln!(f, "=== {}\n**Source:** {}\n{}", self.id, self.location, self.doc)
writeln!(f, "### {}\n**Source:** {}\n{}", self.id, self.location, self.doc)
}
}

21
xtask/src/release.rs
View file

@ -9,7 +9,7 @@ use directories::ProjectDirs;
use stdx::JodChild;
use xshell::{cmd, Shell};
use crate::{codegen, date_iso, flags, is_release_tag, project_root};
use crate::{date_iso, flags, is_release_tag, project_root};
impl flags::Release {
pub(crate) fn run(self, sh: &Shell) -> anyhow::Result<()> {
@ -29,11 +29,6 @@ impl flags::Release {
cmd!(sh, "git push --force").run()?;
}
// Generates bits of manual.adoc.
codegen::diagnostics_docs::generate(false);
codegen::assists_doc_tests::generate(false);
codegen::feature_docs::generate(false);
let website_root = project_root().join("../rust-analyzer.github.io");
{
let _dir = sh.push_dir(&website_root);
@ -54,20 +49,6 @@ impl flags::Release {
.max()
.unwrap_or_default();
for adoc in [
"manual.adoc",
"generated_assists.adoc",
"generated_config.adoc",
"generated_diagnostic.adoc",
"generated_features.adoc",
] {
let src = project_root().join("./docs/user/").join(adoc);
let dst = website_root.join(adoc);
let contents = sh.read_file(src)?;
sh.write_file(dst, contents)?;
}
let tags = cmd!(sh, "git tag --list").read()?;
let prev_tag = tags.lines().filter(|line| is_release_tag(line)).last().unwrap();