aboutsummaryrefslogtreecommitdiff
path: root/docs
diff options
context:
space:
mode:
Diffstat (limited to 'docs')
-rw-r--r--docs/dev/lsp-extensions.md12
-rw-r--r--docs/dev/style.md29
-rw-r--r--docs/user/generated_config.adoc2
-rw-r--r--docs/user/manual.adoc77
4 files changed, 104 insertions, 16 deletions
diff --git a/docs/dev/lsp-extensions.md b/docs/dev/lsp-extensions.md
index f0f981802..8fcd72d5d 100644
--- a/docs/dev/lsp-extensions.md
+++ b/docs/dev/lsp-extensions.md
@@ -1,5 +1,5 @@
1<!--- 1<!---
2lsp_ext.rs hash: 28a9d5a24b7ca396 2lsp_ext.rs hash: 6e57fc1b345b00e9
3 3
4If you need to change the above hash to make the test pass, please check if you 4If you need to change the above hash to make the test pass, please check if you
5need to adjust this doc as well and ping this issue: 5need to adjust this doc as well and ping this issue:
@@ -486,6 +486,16 @@ Primarily for debugging, but very useful for all people working on rust-analyzer
486Returns a textual representation of the HIR of the function containing the cursor. 486Returns a textual representation of the HIR of the function containing the cursor.
487For debugging or when working on rust-analyzer itself. 487For debugging or when working on rust-analyzer itself.
488 488
489## View Crate Graph
490
491**Method:** `rust-analyzer/viewCrateGraph`
492
493**Request:** `null`
494
495**Response:** `string`
496
497Renders rust-analyzer's crate graph as an SVG image.
498
489## Expand Macro 499## Expand Macro
490 500
491**Method:** `rust-analyzer/expandMacro` 501**Method:** `rust-analyzer/expandMacro`
diff --git a/docs/dev/style.md b/docs/dev/style.md
index d24a5952e..f22b69768 100644
--- a/docs/dev/style.md
+++ b/docs/dev/style.md
@@ -636,6 +636,10 @@ use crate::{}
636 636
637// Finally, parent and child modules, but prefer `use crate::`. 637// Finally, parent and child modules, but prefer `use crate::`.
638use super::{} 638use super::{}
639
640// Re-exports are treated as item definitions rather than imports, so they go
641// after imports and modules. Use them sparingly.
642pub use crate::x::Z;
639``` 643```
640 644
641**Rationale:** consistency. 645**Rationale:** consistency.
@@ -694,6 +698,9 @@ Avoid local `use MyEnum::*` imports.
694Prefer `use crate::foo::bar` to `use super::bar` or `use self::bar::baz`. 698Prefer `use crate::foo::bar` to `use super::bar` or `use self::bar::baz`.
695**Rationale:** consistency, this is the style which works in all cases. 699**Rationale:** consistency, this is the style which works in all cases.
696 700
701By default, avoid re-exports.
702**Rationale:** for non-library code, re-exports introduce two ways to use something and allow for inconsistency.
703
697## Order of Items 704## Order of Items
698 705
699Optimize for the reader who sees the file for the first time, and wants to get a general idea about what's going on. 706Optimize for the reader who sees the file for the first time, and wants to get a general idea about what's going on.
@@ -944,6 +951,28 @@ match p.current() {
944 951
945## Documentation 952## Documentation
946 953
954Style inline code comments as proper sentences.
955Start with a capital letter, end with a dot.
956
957```rust
958// GOOD
959
960// Only simple single segment paths are allowed.
961MergeBehavior::Last => {
962 tree.use_tree_list().is_none() && tree.path().map(path_len) <= Some(1)
963}
964
965// BAD
966
967// only simple single segment paths are allowed
968MergeBehavior::Last => {
969 tree.use_tree_list().is_none() && tree.path().map(path_len) <= Some(1)
970}
971```
972
973**Rationale:** writing a sentence (or maybe even a paragraph) rather just "a comment" creates a more appropriate frame of mind.
974It tricks you into writing down more of the context you keep in your head while coding.
975
947For `.md` and `.adoc` files, prefer a sentence-per-line format, don't wrap lines. 976For `.md` and `.adoc` files, prefer a sentence-per-line format, don't wrap lines.
948If the line is too long, you want to split the sentence in two :-) 977If the line is too long, you want to split the sentence in two :-)
949 978
diff --git a/docs/user/generated_config.adoc b/docs/user/generated_config.adoc
index ff4fb064e..e2d74e164 100644
--- a/docs/user/generated_config.adoc
+++ b/docs/user/generated_config.adoc
@@ -1,4 +1,4 @@
1[[rust-analyzer.assist.importMergeBehavior]]rust-analyzer.assist.importMergeBehavior (default: `"full"`):: 1[[rust-analyzer.assist.importMergeBehavior]]rust-analyzer.assist.importMergeBehavior (default: `"crate"`)::
2+ 2+
3-- 3--
4The strategy to use when inserting new imports or merging imports. 4The strategy to use when inserting new imports or merging imports.
diff --git a/docs/user/manual.adoc b/docs/user/manual.adoc
index 58722aaa3..f96c09a79 100644
--- a/docs/user/manual.adoc
+++ b/docs/user/manual.adoc
@@ -6,8 +6,6 @@
6:source-highlighter: rouge 6:source-highlighter: rouge
7:experimental: 7:experimental:
8 8
9// Master copy of this document lives in the https://github.com/rust-analyzer/rust-analyzer repository
10
11At its core, rust-analyzer is a *library* for semantic analysis of Rust code as it changes over time. 9At its core, rust-analyzer is a *library* for semantic analysis of Rust code as it changes over time.
12This manual focuses on a specific usage of the library -- running it as part of a server that implements the 10This manual focuses on a specific usage of the library -- running it as part of a server that implements the
13https://microsoft.github.io/language-server-protocol/[Language Server Protocol] (LSP). 11https://microsoft.github.io/language-server-protocol/[Language Server Protocol] (LSP).
@@ -20,7 +18,6 @@ To improve this document, send a pull request: +
20https://github.com/rust-analyzer/rust-analyzer/blob/master/docs/user/manual.adoc[https://github.com/rust-analyzer/.../manual.adoc] 18https://github.com/rust-analyzer/rust-analyzer/blob/master/docs/user/manual.adoc[https://github.com/rust-analyzer/.../manual.adoc]
21 19
22The manual is written in https://asciidoc.org[AsciiDoc] and includes some extra files which are generated from the source code. Run `cargo test` and `cargo test -p xtask` to create these and then `asciidoctor manual.adoc` to create an HTML copy. 20The manual is written in https://asciidoc.org[AsciiDoc] and includes some extra files which are generated from the source code. Run `cargo test` and `cargo test -p xtask` to create these and then `asciidoctor manual.adoc` to create an HTML copy.
23
24==== 21====
25 22
26If you have questions about using rust-analyzer, please ask them in the https://users.rust-lang.org/c/ide/14["`IDEs and Editors`"] topic of Rust users forum. 23If you have questions about using rust-analyzer, please ask them in the https://users.rust-lang.org/c/ide/14["`IDEs and Editors`"] topic of Rust users forum.
@@ -139,17 +136,6 @@ If you're not using Code, you can compile and install only the LSP server:
139$ cargo xtask install --server 136$ cargo xtask install --server
140---- 137----
141 138
142==== Troubleshooting
143
144Here are some useful self-diagnostic commands:
145
146* **Rust Analyzer: Show RA Version** shows the version of `rust-analyzer` binary.
147* **Rust Analyzer: Status** prints some statistics about the server, and dependency information for the current file.
148* To enable server-side logging, run with `env RA_LOG=info` and see `Output > Rust Analyzer Language Server` in VS Code's panel.
149* To log project loading (sysroot & `cargo metadata`), set `RA_LOG=project_model=debug`.
150* To log all LSP requests, add `"rust-analyzer.trace.server": "verbose"` to the settings and look for `Rust Analyzer Language Server Trace` in the panel.
151* To enable client-side logging, add `"rust-analyzer.trace.extension": true` to the settings and open `Output > Rust Analyzer Client` in the panel.
152
153=== rust-analyzer Language Server Binary 139=== rust-analyzer Language Server Binary
154 140
155Other editors generally require the `rust-analyzer` binary to be in `$PATH`. 141Other editors generally require the `rust-analyzer` binary to be in `$PATH`.
@@ -385,6 +371,68 @@ If available in PATH or in some standard location, `rust-analyzer` is detected a
385If `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. 371If `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.
386You'll need to close and reopen all .rs and Cargo files, or to restart the IDE, for this change to take effect. 372You'll need to close and reopen all .rs and Cargo files, or to restart the IDE, for this change to take effect.
387 373
374=== Kate Text Editor
375
376Support for the language server protocol is built into Kate through the LSP plugin, which is included by default.
377It is preconfigured to use Rls for rust sources, but allows you to use rust-analyzer through a simple settings change.
378In the LSP Client settings of Kate, copy the content of the third tab "default parameters" to the second tab "server configuration".
379Then in the configuration replace:
380[source,json]
381----
382 "rust": {
383 "command": ["rls"],
384 "rootIndicationFileNames": ["Cargo.lock", "Cargo.toml"],
385 "url": "https://github.com/rust-lang/rls",
386 "highlightingModeRegex": "^Rust$"
387 },
388----
389With
390[source,json]
391----
392 "rust": {
393 "command": ["rust-analyzer"],
394 "rootIndicationFileNames": ["Cargo.lock", "Cargo.toml"],
395 "url": "https://github.com/rust-analyzer/rust-analyzer",
396 "highlightingModeRegex": "^Rust$"
397 },
398----
399Then click on apply, and restart the LSP server for your rust project.
400
401== Troubleshooting
402
403Start with looking at the rust-analyzer version.
404Try **Rust Analyzer: Show RA Version** in VS Code and `rust-analyzer --version` in the command line.
405If the date is more than a week ago, it's better to update rust-analyzer version.
406
407The next thing to check would be panic messages in rust-analyzer's log.
408Log messages are printed to stderr, in VS Code you can see then in the `Output > Rust Analyzer Language Server` tab of the panel.
409To see more logs, set `RA_LOG=info` environmental variable.
410
411To fully capture LSP messages between the editor and the server, set `"rust-analyzer.trace.server": "verbose"` config and check
412`Output > Rust Analyzer Language Server Trace`.
413
414The root cause for many "`nothing works`" problems is that rust-analyzer fails to understand the project structure.
415To debug that, first note the `rust-analyzer` section in the status bar.
416If it has an error icon and red, that's the problem (hover will have somewhat helpful error message).
417**Rust Analyzer: Status** prints dependency information for the current file.
418Finally, `RA_LOG=project_model=debug` enables verbose logs during project loading.
419
420If rust-analyzer outright crashes, try running `rust-analyzer analysis-stats /path/to/project/directory/` on the command line.
421This command type checks the whole project in batch mode bypassing LSP machinery.
422
423When filing issues, it is useful (but not necessary) to try to minimize examples.
424An ideal bug reproduction looks like this:
425
426```bash
427$ git clone https://github.com/username/repo.git && cd repo && git switch --detach commit-hash
428$ rust-analyzer --version
429rust-analyzer dd12184e4 2021-05-08 dev
430$ rust-analyzer analysis-stats .
431💀 💀 💀
432```
433
434It is especially useful when the `repo` doesn't use external crates or the standard library.
435
388== Configuration 436== Configuration
389 437
390**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/rust-analyzer/src/config.rs[config.rs] 438**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/rust-analyzer/src/config.rs[config.rs]
@@ -541,6 +589,7 @@ Here is a **non-exhaustive** list of ways to make rust-analyzer execute arbitrar
541 589
542* proc macros and build scripts are executed by default 590* proc macros and build scripts are executed by default
543* `.cargo/config` can override `rustc` with an arbitrary executable 591* `.cargo/config` can override `rustc` with an arbitrary executable
592* `rust-toolchain.toml` can override `rustc` with an arbitrary executable
544* 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. 593* 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.
545* rust-analyzer's syntax trees library uses a lot of `unsafe` and hasn't been properly audited for memory safety. 594* rust-analyzer's syntax trees library uses a lot of `unsafe` and hasn't been properly audited for memory safety.
546 595