mirror of
https://github.com/rust-lang/rust-analyzer
synced 2025-02-13 04:33:28 +00:00
Merge pull request #19015 from Wilfred/mdbook
manual: Convert to mdbook
This commit is contained in:
commit
07a09c154e
70 changed files with 2836 additions and 2686 deletions
.gitignore
crates
ide-assists/src
ide-completion/src
ide-db/src
ide-diagnostics/src/handlers
ide-ssr/src
ide/src
annotations.rsdoc_links.rsexpand_macro.rsextend_selection.rsfetch_crates.rsfile_structure.rsgoto_definition.rsgoto_implementation.rsgoto_type_definition.rshighlight_related.rshover.rsinlay_hints.rsinterpret.rsjoin_lines.rsmatching_brace.rsmove_item.rsparent_module.rsreferences.rsrename.rsrunnables.rsstatus.rssyntax_highlighting.rstyping.rs
typing
view_crate_graph.rsview_hir.rsview_item_tree.rsview_memory_layout.rsview_mir.rsview_syntax_tree.rsparser/src/syntax_kind
rust-analyzer/src
syntax/src/ast/generated
docs
xtask/src
7
.gitignore
vendored
7
.gitignore
vendored
|
@ -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
|
||||
|
|
|
@ -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
|
||||
|
|
|
@ -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
|
||||
//
|
||||
|
|
|
@ -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;
|
||||
|
||||
|
|
|
@ -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
|
||||
|
|
|
@ -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},
|
||||
|
|
|
@ -106,11 +106,13 @@ impl CompletionFieldsToResolve {
|
|||
//
|
||||
// There also snippet completions:
|
||||
//
|
||||
// .Expressions
|
||||
// #### Expressions
|
||||
//
|
||||
// - `pd` -> `eprintln!(" = {:?}", );`
|
||||
// - `ppd` -> `eprintln!(" = {:#?}", );`
|
||||
//
|
||||
// .Items
|
||||
// #### Items
|
||||
//
|
||||
// - `tfn` -> `#[test] fn feature(){}`
|
||||
// - `tmod` ->
|
||||
// ```rust
|
||||
|
@ -127,7 +129,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.
|
||||
///
|
||||
|
|
|
@ -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;
|
||||
|
|
|
@ -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![];
|
||||
|
||||
|
|
|
@ -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();
|
||||
|
||||
|
|
|
@ -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"),
|
||||
|
|
|
@ -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
|
||||
|
|
|
@ -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,
|
||||
|
|
|
@ -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,
|
||||
|
|
|
@ -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);
|
||||
|
|
|
@ -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);
|
||||
|
|
|
@ -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
|
||||
|
|
|
@ -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();
|
||||
|
|
|
@ -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,
|
||||
|
|
|
@ -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,
|
||||
|
|
|
@ -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,
|
||||
|
|
|
@ -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(
|
||||
|
|
|
@ -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,
|
||||
|
|
|
@ -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,
|
||||
|
|
|
@ -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)) => {
|
||||
|
|
|
@ -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,
|
||||
|
|
|
@ -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![|]];
|
||||
|
|
|
@ -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,
|
||||
|
|
|
@ -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> {
|
||||
|
|
|
@ -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,
|
||||
|
|
|
@ -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,
|
||||
|
|
|
@ -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,
|
||||
|
|
|
@ -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();
|
||||
|
||||
|
|
|
@ -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,
|
||||
|
|
|
@ -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,
|
||||
|
|
|
@ -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();
|
||||
|
|
|
@ -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
|
||||
|
|
|
@ -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())
|
||||
}
|
||||
|
|
|
@ -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
|
||||
|
|
|
@ -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,
|
||||
|
|
|
@ -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())
|
||||
}
|
||||
|
|
|
@ -15,11 +15,9 @@ use triomphe::Arc;
|
|||
//
|
||||
// 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 line_index = db.line_index(file_id);
|
||||
|
|
|
@ -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;
|
||||
|
|
|
@ -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);
|
||||
}
|
||||
|
|
|
@ -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::{
|
||||
|
|
|
@ -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
29
docs/book/README.md
Normal 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
41
docs/book/book.toml
Normal 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
21
docs/book/src/README.md
Normal 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
13
docs/book/src/SUMMARY.md
Normal 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
8
docs/book/src/assists.md
Normal 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
51
docs/book/src/configuration.md
Normal 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
1201
docs/book/src/configuration_generated.md
Normal file
File diff suppressed because it is too large
Load diff
16
docs/book/src/diagnostics.md
Normal file
16
docs/book/src/diagnostics.md
Normal 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
204
docs/book/src/editor_features.md
Normal 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
3
docs/book/src/features.md
Normal file
|
@ -0,0 +1,3 @@
|
|||
# Features
|
||||
|
||||
{{#include features_generated.md:2:}}
|
644
docs/book/src/installation.md
Normal file
644
docs/book/src/installation.md
Normal 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 >
|
||||
Preferences > 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
246
docs/book/src/non_cargo_based_projects.md
Normal 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
15
docs/book/src/privacy.md
Normal 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
19
docs/book/src/security.md
Normal 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
50
docs/book/src/troubleshooting.md
Normal 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)!
|
|
@ -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
1
docs/user/.gitignore
vendored
|
@ -1 +0,0 @@
|
|||
manual.html
|
File diff suppressed because it is too large
Load diff
File diff suppressed because it is too large
Load diff
|
@ -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()
|
||||
|
|
|
@ -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,
|
||||
|
|
|
@ -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)
|
||||
}
|
||||
}
|
||||
|
|
|
@ -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)
|
||||
}
|
||||
}
|
||||
|
|
|
@ -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();
|
||||
|
||||
|
|
Loading…
Reference in a new issue