Manual updates #7113
Manual updates #7113
Conversation
- Add link to asciidoc website - Explain how to create the generated adoc files from the source code - How to run asciidoctor to generate the manual
|
bors r+ Thanks! |
7113: Manual updates r=matklad a=tekul Add some details on how to build the manual and some clarification on how to deal with "proc macro2 warnings. For context, this arose from [this question](https://users.rust-lang.org/t/how-to-disable-rust-analyzer-proc-macro-warnings-in-neovim/53150) on users.rust-lang.org. Co-authored-by: Luke Taylor <[email protected]>
|
Build failed: |
|
Looks like I screwed a couple of things up. How do I update the |
|
See |
crates/rust-analyzer/src/config.rs
Outdated
| @@ -153,7 +153,8 @@ config_data! { | |||
| /// Whether to show `can't find Cargo.toml` error message. | |||
| notifications_cargoTomlNotFound: bool = "true", | |||
| /// Enable Proc macro support, `#rust-analyzer.cargo.loadOutDirsFromCheck#` must be | |||
| /// enabled. | |||
| /// enabled. This has nothing to do with "proc macro not expanded" warnings. See the | |||
There was a problem hiding this comment.
This has nothing to do with "proc macro not expanded" warnings
That doesn't seem right to me? The "proc macro not expanded" warnings are emitted when we encounter proc macro calls, but this setting is disabled, so they have a lot to do with each other.
There was a problem hiding this comment.
The warnings seem to be shown whether this setting is enabled or not. That is what I was attempting to capture here. I hadn't actually heard of a "proc macro" before this (though I now have some idea what they are 🙂 ). I expect a lot of users who see this message when using rust-analyzer won't really know either. I'm still not sure what this setting is for, but I guess it is only required if you are writing macros and have the corresponding flag set in your crate. Is that correct?
There was a problem hiding this comment.
I hadn't actually heard of a "proc macro" before this
If you've used serde, that was a proc macro. They're called procedural macros because they're Rust functions that are called with bits of text and return other bits of Rust code. That's unlike declarative macros (or "macros by example"), which define input templates and rules for how they need to be transformed.
A proc macro lives in a Rust crate that needs to be compiled, then loaded at run-time by the compiler (so that it's able to call the function in there). We're not the compiler, but we do the same thing to expand procedural macros, but only if rust-analyzer.procMacro.enable (because of #6448).
The warnings seem to be shown whether this setting is enabled or not.
I think they shouldn't be shown if it's enabled. They shouldn't even be warnings, I guess. That message is there only to tell users about the setting.
There was a problem hiding this comment.
Thanks, you are right. The warnings do go away with this enabled. I'm not sure why this didn't work for me the first time I tried it. I probably had a typo in the nvim lua settings. So this change is definitely wrong. Shall I change it to to something along the lines of "If you are seeing 'proc macro not expanded' warnings, enabling this property should stop them. Alternatively you can disable the unresolved-proc-macro diagnostic"?
There was a problem hiding this comment.
Shall I change it to to something along the lines of "If you are seeing 'proc macro not expanded' warnings, enabling this property should stop them. Alternatively you can disable the unresolved-proc-macro diagnostic"?
That sounds correct. It might be too verbose, but I'm not sure how verbose the descriptions usually are.
This seems to print the same output as running the test, but it's not obvious how to update the |
I've no idea, those were added only recently. The difference is that these two (at least) only apply to the Code extension, and not to the language server (so the Rust code doesn't care about them). |
Added the error message to the doc for the UnresolvedProcMacro diagnostic, explaining that either enabling the procMacro setting or disabling this diagnostic should make the warnings go away.
|
I've redone this, removing the doc from the |
|
bors r+ |
Add some details on how to build the manual and some clarification on how to deal with "proc macro2 warnings.
For context, this arose from this question on users.rust-lang.org.