-
Notifications
You must be signed in to change notification settings - Fork 12.7k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Render more readable macro matcher tokens in rustdoc #92908
Conversation
src/librustdoc/clean/utils.rs
Outdated
"as" | "box" | "break" | "const" | "continue" | "crate" | "else" | "enum" | "extern" | ||
| "for" | "if" | "impl" | "in" | "let" | "loop" | "macro" | "match" | "mod" | "move" | ||
| "mut" | "ref" | "return" | "static" | "struct" | "trait" | "type" | "unsafe" | "use" | ||
| "where" | "while" | "yield" => true, | ||
_ => false, |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This seems really brittle. Is there some way we can call a function in rustc to get this information? Symbol::is_used_keyword_conditional
looks promising.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
rustc_span has functions for evaluating whether a Symbol is a reserved word, or is a keyword on a particular edition.
This logic isn't that though. It is quite specific to rendering spacing in stringified token streams. I would not expect to find a function for that in rustc, because here in rustdoc is the first place that cares about nicely stringifying token streams in a way that human users of the language are expected to regularly encounter.
I pushed a commit that inverts the list though, since among keywords there are fewer that do not need a space than need a space. Let me know you like that better.
I'll take another look at this soon. Thanks for the very clear and helpful comments. ❤️ cc @GuillaumeGomez in case you want to review as well |
Could you add another "more complete" HTML test please? |
Let me do that after #92914 has landed and I've rebased. |
…omez htmldocck: Add support for `/text()` in `@snapshot` This allows just testing the text, in cases where the HTML tags don't matter. See rust-lang#92908 (comment) for an example of when this would be useful. r? `@GuillaumeGomez`
Looks good to me, thanks! Let's wait for @camelid approval as well. |
I feel a little uncomfortable about having so much custom code for a fairly niche use case (macro-generated macros), but I won't block it. I guess we could always delete this code if we had to since it's not part of our stability guarantee. |
I don't agree that this is niche -- doesn't this affect all standard library macros according to #86208 / #92334 (review)? That seems front and center for a large fraction of the macros that users of Rust are going to be looking at. |
I thought your previous PR (#92334) already fixed most cases? |
Your review comment on that PR says "it won't fix the rendering of macros in the standard library since the lack of sources there triggered the switch to pretty-printing in the first place". The screenshot above is from https://doc.rust-lang.org/nightly/std/macro.write.html so it confirms that the source-based rendering does not kick in for the standard macros. Maybe that can be solved a different way but for now #92334 by itself does not fix it. |
Oops, it looks like I should've listened to past me ;) I think this change is reasonable then. Sorry for the confusion! |
Thanks for working on this! @bors: r+ |
📌 Commit 039a058 has been approved by |
Rollup of 5 pull requests Successful merges: - rust-lang#92887 (Bootstrap compiler update) - rust-lang#92908 (Render more readable macro matcher tokens in rustdoc) - rust-lang#93183 (rustdoc: mobile nav fixes) - rust-lang#93192 (Add VS 2022 into error message) - rust-lang#93475 (Add test to ensure that theme is applied correctly when going back in history) Failed merges: r? `@ghost` `@rustbot` modify labels: rollup
Follow-up to #92334.
This PR lifts some of the token rendering logic from https://github.com/dtolnay/prettyplease into rustdoc so that even the matchers for which a source code snippet is not available (because they are macro-generated, or any other reason) follow some baseline good assumptions about where the tokens in the macro matcher are appropriate to space.
The below screenshots show an example of the difference using one of the gnarliest macros I could find. Some things to notice:
In the before, notice how a couple places break in between
$(....)
↵*
, which is just about the worst possible place that it could break.In the before, the lines that wrapped are weirdly indented by 1 space of indentation relative to column 0. In the after, we use the typical way of block indenting in Rust syntax which is put the open/close delimiters on their own line and indent their contents by 4 spaces relative to the previous line (so 8 spaces relative to column 0, because the matcher itself is indented by 4 relative to the
macro_rules
header).In the after, macro_rules metavariables like
$tokens:tt
are kept together, which is how just about everybody writing Rust today writes them.Before
After
r? @camelid