rustdoc: Use own logic to print `#[repr(..)]` attributes in JSON output. #138018

obi1kenobi · 2025-03-04T22:12:18Z

Switch away from Debug-like representation of #[repr(..)] attributes, and start using rustdoc's own logic for pretty-printing #[repr(..)] in rustdoc JSON.

Part of addressing #137645 but not a complete solution for it.

r? @aDotInTheVoid

rustbot · 2025-03-05T06:45:53Z

rustdoc-json-types is a public (although nightly-only) API. If possible, consider changing src/librustdoc/json/conversions.rs; otherwise, make sure you bump the FORMAT_VERSION constant.

cc @CraftSpider, @aDotInTheVoid, @Enselic, @obi1kenobi

Some changes occurred in tests/rustdoc-json

cc @aDotInTheVoid

aDotInTheVoid

This looks really good! Thanks for the very thorough tests, it's appreciated.

Could you update the docs on Item::attribute? After that and rebasing to bump the format version again, this should be good to merge.

tests/rustdoc-json/attrs/repr_transparent.rs

aDotInTheVoid · 2025-03-11T22:51:50Z

src/rustdoc-json-types/lib.rs

@@ -30,7 +30,7 @@ pub type FxHashMap<K, V> = HashMap<K, V>; // re-export for use in src/librustdoc
 /// This integer is incremented with every breaking change to the API,
 /// and is returned along with the JSON blob as [`Crate::format_version`].
 /// Consuming code should assert that this value matches the format version(s) that it supports.
-pub const FORMAT_VERSION: u32 = 40;
+pub const FORMAT_VERSION: u32 = 41;


Another PR currently in the queue is making this change: #138109 (comment)

Once that lands, you should rebase ontop of that, and then bump again.

obi1kenobi · 2025-03-12T05:21:35Z

Happy to do it, though I'm currently traveling for another week so it won't be soon. I'd be thrilled to have this merged ASAP though, so if you'd like to make the necessary changes and then merge, go for it. I don't care whose name is on the commit :)

…

On Tue, Mar 11, 2025, 4:55 PM Alona Enraght-Moony ***@***.***> wrote: ***@***.**** commented on this pull request. This looks really good! Thanks for the very thorough tests, it's appreciated. Could you update the docs on Item::attribute? After that and rebasing to bump the format version again, this should be good to merge. ------------------------------ In tests/rustdoc-json/attrs/repr_transparent.rs <#138018 (comment)>: > @@ -0,0 +1,35 @@ +#![no_std] + +// Rustdoc JSON *only* includes `#[repr(transparent)]` +// if the transparency is public API: +// - if a non-1-ZST field exists, it has to be public +// - otherwise, all fields are 1-ZST and at least one of them is public NIT: It'd be nice to cite where these rules come from: https://doc.rust-lang.org/nomicon/other-reprs.html#reprtransparent ------------------------------ In src/rustdoc-json-types/lib.rs <#138018 (comment)>: > @@ -30,7 +30,7 @@ pub type FxHashMap<K, V> = HashMap<K, V>; // re-export for use in src/librustdoc /// This integer is incremented with every breaking change to the API, /// and is returned along with the JSON blob as [`Crate::format_version`]. /// Consuming code should assert that this value matches the format version(s) that it supports. -pub const FORMAT_VERSION: u32 = 40; +pub const FORMAT_VERSION: u32 = 41; Another PR currently in the queue is making this change: #138109 (comment) <#138109 (comment)> Once that lands, you should rebase ontop of that, and then bump again. — Reply to this email directly, view it on GitHub <#138018 (review)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAR5MSQMCSMYZWTJIBFBHC32T5SVVAVCNFSM6AAAAABYKTDHVCVHI2DSMVQWIX3LMV43YUDVNRWFEZLROVSXG5CSMV3GSZLXHMZDMNZWGE4TONJSG4> . You are receiving this because you were mentioned.Message ID: ***@***.***>

bors · 2025-03-16T06:14:22Z

☔ The latest upstream changes (presumably #138548) made this pull request unmergeable. Please resolve the merge conflicts.

aDotInTheVoid · 2025-03-16T20:39:35Z

I've done the test changes in only in #138569. I'll look at the content changes in a bit (if you don't get around to it first).

Good thing about doing tests before impl change: It tells you more about what's being changed. In this case, we go from always showing #[repr(transparent)], to only showing #[repr(transparent)] when it's a part of the public API. Still not sure that's a the right choice.

…laumeGomez rustdoc-json: Add tests for `#[repr(...)]` Works towards rust-lang#137645 and rust-lang#81359 Based on rust-lang#138018, but with only the test changes. CC `@obi1kenobi` r? `@GuillaumeGomez`

…laumeGomez rustdoc-json: Add tests for `#[repr(...)]` Works towards rust-lang#137645 and rust-lang#81359 Based on rust-lang#138018, but with only the test changes. CC ``@obi1kenobi`` r? ``@GuillaumeGomez``

…laumeGomez rustdoc-json: Add tests for `#[repr(...)]` Works towards rust-lang#137645 and rust-lang#81359 Based on rust-lang#138018, but with only the test changes. CC ```@obi1kenobi``` r? ```@GuillaumeGomez```

obi1kenobi · 2025-03-19T00:18:50Z

Good thing about doing tests before impl change: It tells you more about what's being changed. In this case, we go from always showing #[repr(transparent)], to only showing #[repr(transparent)] when it's a part of the public API. Still not sure that's a the right choice.

My arguments for the behavior change are:

Consistency between HTML and JSON output is desirable; not changing means rustdoc HTML and JSON disagree on the item attributes: JSON always shows it, HTML only shows it if public API.
Always including repr(transparent) makes that the only non-public-API element present in rustdoc JSON with default settings. This feels much more like a bug than a feature.
- When not public API, repr(transparent) is an internal implementation detail analogous to a method body or a non-public-API type. Those aren't included in rustdoc JSON either at all (method bodies) or without a specific flag combination (--document-hidden-items --document-private-items). If included, the item can be determined to be non-public-API from the rustdoc JSON itself.
- This suggests non-public-API repr(transparent) should either be omitted entirely (like a method body), or at minimum should only be included if a specific flag is added and if it's possible to determine its "public API" status from the JSON alone (which it currently is not).

I hope you find these arguments convincing :) If not, then in the interest of merging the rest of the PR quickly (important for cargo-semver-checks!), I can separate out the behavior change into its own PR so we can discuss it separately.

aDotInTheVoid · 2025-03-21T00:46:19Z

Yeah fair enough that makes sense. Maybe oneday --document-private-items should include it on both HTML and JSON, but that can happen later/seperatly.

obi1kenobi · 2025-03-21T00:58:10Z

FWIW I hope we get an explicit repr section (like the one for #[deprecated]) in items before that happens, so that we can get an explicit privacy indicator. The current change will improve the accuracy of the cargo-semver-checks lint for #[repr(transparent)] removals, but since we currently have to use --document-private-items to precisely resolve glob imports, adding #[repr(transparent)] back with that flag will undo that accuracy improvement.

Rebasing this commit and resolving merge conflicts now. Should be updated momentarily.

aDotInTheVoid

Code/test changes look good to me. This can be merged after updating the docs, and rebasing on top of #138763 (which is currently in the queue and this will conflict with)

aDotInTheVoid · 2025-03-22T14:11:26Z

src/rustdoc-json-types/lib.rs

@@ -30,7 +30,7 @@ pub type FxHashMap<K, V> = HashMap<K, V>; // re-export for use in src/librustdoc
 /// This integer is incremented with every breaking change to the API,
 /// and is returned along with the JSON blob as [`Crate::format_version`].
 /// Consuming code should assert that this value matches the format version(s) that it supports.
-pub const FORMAT_VERSION: u32 = 42;
+pub const FORMAT_VERSION: u32 = 43;


The docs for Item::attrs should be updated to explain what's happened here.

Done; I also updated the Item::attrs comment to also explain that the #[deprecated] attribute is no longer present there (a change we made previously but wasn't mentioned explicitly in the doc).

obi1kenobi · 2025-03-22T14:33:04Z

Updated the docs; waiting for the other PR to merge so I can rebase. Can I r=you after the rebase or would you like to take another look?

aDotInTheVoid · 2025-03-22T16:18:17Z

r=me after rebasing once the test change lands

@bors delegate+

@bors rollup

bors · 2025-03-22T16:18:20Z

✌️ @obi1kenobi, you can now approve this pull request!

If @aDotInTheVoid told you to "r=me" after making some further change, please make that change, then do @bors r=@aDotInTheVoid

bors · 2025-03-22T18:07:07Z

☔ The latest upstream changes (presumably #138830) made this pull request unmergeable. Please resolve the merge conflicts.

obi1kenobi · 2025-03-22T18:51:43Z

@bors r=@aDotInTheVoid

bors · 2025-03-22T18:51:46Z

📌 Commit bafdbca has been approved by aDotInTheVoid

It is now in the queue for this repository.

…iaskrgr Rollup of 8 pull requests Successful merges: - rust-lang#138018 (rustdoc: Use own logic to print `#[repr(..)]` attributes in JSON output.) - rust-lang#138294 (Mark some std tests as requiring `panic = "unwind"`) - rust-lang#138468 (rustdoc js: add nonnull helper and typecheck src-script.js) - rust-lang#138675 (Add release notes for 1.85.1) - rust-lang#138765 (Fix Thread::set_name on cygwin) - rust-lang#138786 (Move some driver code around) - rust-lang#138793 (target spec check: better error when llvm-floatabi is missing) - rust-lang#138822 (De-Stabilize `file_lock`) r? `@ghost` `@rustbot` modify labels: rollup

Rollup merge of rust-lang#138018 - obi1kenobi:pg/librustdoc_repr_attr, r=aDotInTheVoid rustdoc: Use own logic to print `#[repr(..)]` attributes in JSON output. Switch away from `Debug`-like representation of `#[repr(..)]` attributes, and start using rustdoc's own logic for pretty-printing `#[repr(..)]` in rustdoc JSON. Part of addressing rust-lang#137645 but not a complete solution for it. r? `@aDotInTheVoid`

rustbot assigned aDotInTheVoid Mar 4, 2025

rustbot added S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue. labels Mar 4, 2025

obi1kenobi mentioned this pull request Mar 4, 2025

rustdoc-json: Improve Item::attrs to not use debug representation. #137645

Open

aDotInTheVoid added A-attributes Area: Attributes (`#[…]`, `#![…]`) A-rustdoc-json Area: Rustdoc JSON backend labels Mar 4, 2025

obi1kenobi force-pushed the pg/librustdoc_repr_attr branch from 98cba84 to 67e9486 Compare March 5, 2025 06:45

rustbot added A-rustdoc-search Area: Rustdoc's search feature T-rustdoc-frontend Relevant to the rustdoc-frontend team, which will review and decide on the web UI/UX output. labels Mar 5, 2025

obi1kenobi marked this pull request as ready for review March 5, 2025 06:45

aDotInTheVoid removed A-rustdoc-search Area: Rustdoc's search feature T-rustdoc-frontend Relevant to the rustdoc-frontend team, which will review and decide on the web UI/UX output. labels Mar 11, 2025

aDotInTheVoid reviewed Mar 11, 2025

View reviewed changes

aDotInTheVoid mentioned this pull request Mar 11, 2025

rustdoc-json: Guard agains 2 commits making the same modification to FORMAT_VERSION #94591

Open

aDotInTheVoid mentioned this pull request Mar 16, 2025

rustdoc-json: Add tests for #[repr(...)] #138569

Merged

obi1kenobi force-pushed the pg/librustdoc_repr_attr branch 2 times, most recently from 743870f to 724900a Compare March 21, 2025 01:03

This comment has been minimized.

Sign in to view

obi1kenobi force-pushed the pg/librustdoc_repr_attr branch from 724900a to f7c8539 Compare March 21, 2025 04:28

aDotInTheVoid reviewed Mar 22, 2025

View reviewed changes

obi1kenobi force-pushed the pg/librustdoc_repr_attr branch from f7c8539 to fe20ada Compare March 22, 2025 14:31

aDotInTheVoid approved these changes Mar 22, 2025

View reviewed changes

rustdoc: Use own logic to print #[repr(..)] attributes in JSON output.

bafdbca

obi1kenobi force-pushed the pg/librustdoc_repr_attr branch from fe20ada to bafdbca Compare March 22, 2025 18:47

bors added S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Mar 22, 2025

matthiaskrgr mentioned this pull request Mar 22, 2025

Rollup of 8 pull requests #138841

Merged

bors merged commit c5a5f8a into rust-lang:master Mar 23, 2025
6 checks passed

rustbot added this to the 1.87.0 milestone Mar 23, 2025

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

rustdoc: Use own logic to print `#[repr(..)]` attributes in JSON output. #138018

rustdoc: Use own logic to print `#[repr(..)]` attributes in JSON output. #138018

obi1kenobi commented Mar 4, 2025

rustbot commented Mar 5, 2025

aDotInTheVoid left a comment

aDotInTheVoid Mar 11, 2025

obi1kenobi commented Mar 12, 2025 via email

bors commented Mar 16, 2025

aDotInTheVoid commented Mar 16, 2025

obi1kenobi commented Mar 19, 2025 •

edited

Loading

aDotInTheVoid commented Mar 21, 2025

obi1kenobi commented Mar 21, 2025

This comment has been minimized.

aDotInTheVoid left a comment

aDotInTheVoid Mar 22, 2025

obi1kenobi Mar 22, 2025 •

edited

Loading

obi1kenobi commented Mar 22, 2025

aDotInTheVoid commented Mar 22, 2025

bors commented Mar 22, 2025

bors commented Mar 22, 2025

obi1kenobi commented Mar 22, 2025

bors commented Mar 22, 2025

rustdoc: Use own logic to print #[repr(..)] attributes in JSON output. #138018

rustdoc: Use own logic to print #[repr(..)] attributes in JSON output. #138018

Conversation

obi1kenobi commented Mar 4, 2025

rustbot commented Mar 5, 2025

aDotInTheVoid left a comment

Choose a reason for hiding this comment

aDotInTheVoid Mar 11, 2025

Choose a reason for hiding this comment

obi1kenobi commented Mar 12, 2025 via email

bors commented Mar 16, 2025

aDotInTheVoid commented Mar 16, 2025

obi1kenobi commented Mar 19, 2025 • edited Loading

aDotInTheVoid commented Mar 21, 2025

obi1kenobi commented Mar 21, 2025

This comment has been minimized.

aDotInTheVoid left a comment

Choose a reason for hiding this comment

aDotInTheVoid Mar 22, 2025

Choose a reason for hiding this comment

obi1kenobi Mar 22, 2025 • edited Loading

Choose a reason for hiding this comment

obi1kenobi commented Mar 22, 2025

aDotInTheVoid commented Mar 22, 2025

bors commented Mar 22, 2025

bors commented Mar 22, 2025

obi1kenobi commented Mar 22, 2025

bors commented Mar 22, 2025

rustdoc: Use own logic to print `#[repr(..)]` attributes in JSON output. #138018

rustdoc: Use own logic to print `#[repr(..)]` attributes in JSON output. #138018

obi1kenobi commented Mar 19, 2025 •

edited

Loading

obi1kenobi Mar 22, 2025 •

edited

Loading