rustdoc-json: Structured attributes #142936

aDotInTheVoid · 2025-06-23T23:28:10Z

Implements #141358.

This has 2 primary benefits.

For rustdoc-json consumers, they no longer need to parse strings of attributes, but it's there in a structured and normalized way. CC @obi1kenobi
For rustc conributors, the output of HIR pretty printing is no longer a versioned thing in the output. People can work on Tracking issue: Attribute refactor #131229 without needing to bump FORMAT_VERSION. CC @jdonszelmann @JonathanBrouwer.

(Over time, as the attribute refractor continues, I expect we'll add new things to rustdoc_json_types::Attribute. But this can be done separately to the rustc changes).

Todo before being mergable:

Update test assertions.
Fix modeling of #[repr].
~~Add tests of #[doc(hidden)] in Item::attrs (probably in a seperate PR).~~ I'm gonna punt this to a future PR
Documentation.

rustbot · 2025-06-23T23:28:15Z

r? @notriddle

rustbot has assigned @notriddle.
They will have a look at your PR within the next two weeks and either review your PR or reassign to another reviewer.

Use r? to explicitly pick a reviewer

rustbot · 2025-06-23T23:28:18Z

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

jdonszelmann · 2025-06-23T23:35:46Z

Awesome alona! I'll take a proper look tomorrow <3

obi1kenobi

I like this!

In the near term cargo-semver-checks will have to internally re-stringify the attributes just for code compatibility with prior rustdoc JSON versions. But I look forward to the day when I can rip all that out and enjoy the structured form instead!

src/rustdoc-json-types/lib.rs

bors · 2025-06-24T05:47:03Z

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

src/rustdoc-json-types/lib.rs

rustbot · 2025-06-24T19:27:17Z

r? @GuillaumeGomez

rustbot has assigned @GuillaumeGomez.
They will have a look at your PR within the next two weeks and either review your PR or reassign to another reviewer.

Use r? to explicitly pick a reviewer

rustbot · 2025-06-24T19:27:18Z

These commits modify tests/rustdoc-json.
rustdoc-json is a public (but unstable) interface.

Please ensure that if you've changed the output:

It's intentional.
The FORMAT_VERSION in src/librustdoc-json-types is bumped if necessary.

cc @aDotInTheVoid, @obi1kenobi

aDotInTheVoid · 2025-06-24T19:28:16Z

Now no longer WIP.

When you're happy with it, let me know but don't r+, as I'll need to squash commits.

obi1kenobi

Very nice! Looking forward to this!

obi1kenobi · 2025-06-24T23:23:16Z

src/librustdoc/clean/types.rs

+                // NoMangle is special cased, as it's currently the only structured
+                // attribute that we want to appear in HTML output.


As a separate concern unrelated to this PR, perhaps HTML output should list both #[no_mangle] and #[export_name] in their edition 2024 form i.e. wrapped in unsafe?

Please open an issue then so it's not forgotten.

We already track this in #142835 (comment) (jana is assigned)

tests/rustdoc-json/attrs/must_use.rs

tests/rustdoc-json/attrs/repr_c_int_enum.rs

GuillaumeGomez

Changes look good to me. It's nice to see less is_json conditions in the common code. :)

bors · 2025-06-27T04:59:44Z

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

aDotInTheVoid · 2025-07-07T22:06:46Z

src/rustdoc-json-types/lib.rs

+/// The contents of a `#[repr(...)]` attribute.
+///
+/// Used in [`Attribute::Repr`].
+pub struct AttributeRepr {


CC @workingjubilee, how does this look for a structured representation of a #[repr] attribute?

Implements rust-lang#141358. This has 2 primary benefits: 1. For rustdoc-json consumers, they no longer need to parse strings of attributes, but it's there in a structured and normalized way. 2. For rustc contributors, the output of HIR pretty printing is no longer a versioned thing in the output. People can work on rust-lang#131229 without needing to bump `FORMAT_VERSION`. (Over time, as the attribute refractor continues, I expect we'll add new things to `rustdoc_json_types::Attribute`. But this can be done separately to the rustc changes).

aDotInTheVoid · 2025-07-07T22:31:20Z

Rebased. I think this is worth reviewing again, as it's changed it response to changes to rustc since intially opening.

@rustbot ready.

obi1kenobi

LGTM, big fan of this overall. A handful of small typo fix nits.

obi1kenobi · 2025-07-08T02:40:11Z

src/librustdoc/clean/types.rs

-                // NoMangle is special cased, as it appears in HTML output, and we want to show it in source form, not HIR printing.
-                // It is also used by cargo-semver-checks.
-                else if let hir::Attribute::Parsed(AttributeKind::NoMangle(..)) = attr {
+                } else if let hir::Attribute::Parsed(AttributeKind::NoMangle(..)) = attr {


A bit of a drive-by, but should we update these to Rust 2024 edition form? #[unsafe(no_mangle)], #[unsafe(export_name = ...)] etc.

obi1kenobi · 2025-07-08T02:42:32Z

src/librustdoc/clean/types.rs

+                } else if !attr.has_any_name(ALLOWED_ATTRIBUTES) {
+                    None


Out of curiosity, since I'm a bit confused here:

I see ALLOWED_ATTRIBUTES contains sym::non_exhaustive.

I see #[non_exhaustive] in the else if arm right above this.

Is there a case where a non-exhaustive might slip through the earlier check and then match the .has_any_name()?

obi1kenobi · 2025-07-08T02:44:50Z

src/librustdoc/json/conversions.rs

+    };
+
+    Some(match kind {
+        AK::Deprecation { .. } => return None, // Handled seperatly into Item::deprecation.


typo fix:

Suggested change

AK::Deprecation { .. } => return None, // Handled seperatly into Item::deprecation.

AK::Deprecation { .. } => return None, // Handled separately into Item::deprecation.

obi1kenobi · 2025-07-08T02:47:12Z

src/librustdoc/json/conversions.rs

+        AK::TargetFeature(features, _span) => Attribute::TargetFeature(
+            features.iter().map(|(feat, _span)| feat.to_string()).collect(),
+        ),


Just a heads-up: there's an RFC being prepared to add two flavors of #[target_feature]: enable and force, each of which has its own list of feature names.

We don't have to make a proactive change to make that happen, but I think the RFC has decent odds of passing so I wanted to mention it for general awareness & in case you felt you wanted to change anything.

obi1kenobi · 2025-07-08T02:48:08Z

src/rustdoc-json-types/lib.rs

    /// Information about the item’s deprecation, if present.
    pub deprecation: Option<Deprecation>,
    /// The type-specific fields describing this item.
    pub inner: ItemEnum,
 }

+#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+/// An attribute, eg `#[repr(C)]`


nit:

Suggested change

/// An attribute, eg `#[repr(C)]`

/// An attribute, e.g. `#[repr(C)]`

obi1kenobi · 2025-07-08T02:50:18Z

src/rustdoc-json-types/lib.rs

+    /// Things here are explicitly *not* covered by the [`FORMAT_VERSION`]
+    /// constant, and may change without bumping the format version.


nit: Since #[doc(hidden)] is super critical to cargo-semver-checks I hope we can be mindful of it with respect to this clause. I wouldn't insist on special-casing it here and I know you are planning to tackle it soon — just wanted to raise a possible concern pre-emptively :)

rustbot assigned notriddle Jun 23, 2025

aDotInTheVoid unassigned notriddle Jun 23, 2025

aDotInTheVoid marked this pull request as draft June 23, 2025 23:28

aDotInTheVoid mentioned this pull request Jun 23, 2025

Rework #[cold] attribute parser #142491

Merged

aDotInTheVoid added the A-attributes Area: Attributes (`#[…]`, `#![…]`) label Jun 23, 2025

This comment has been minimized.

Sign in to view

obi1kenobi reviewed Jun 24, 2025

View reviewed changes

src/rustdoc-json-types/lib.rs Outdated Show resolved Hide resolved

src/rustdoc-json-types/lib.rs Show resolved Hide resolved

src/rustdoc-json-types/lib.rs Show resolved Hide resolved

aDotInTheVoid mentioned this pull request Jun 24, 2025

rustdoc-json: Add test for #[optimize(..)] #142916

Merged

JonathanBrouwer reviewed Jun 24, 2025

View reviewed changes

src/rustdoc-json-types/lib.rs Show resolved Hide resolved

aDotInTheVoid changed the title ~~WIP: rustdoc-json: Structured attributes~~ rustdoc-json: Structured attributes Jun 24, 2025

aDotInTheVoid marked this pull request as ready for review June 24, 2025 19:27

rustbot assigned GuillaumeGomez Jun 24, 2025

rust-cloud-vms bot force-pushed the rdj-shatts-forrealthistime branch from 1d4b795 to c912543 Compare June 24, 2025 19:27

This comment has been minimized.

Sign in to view

obi1kenobi reviewed Jun 24, 2025

View reviewed changes

GuillaumeGomez approved these changes Jun 25, 2025

View reviewed changes

rust-cloud-vms bot force-pushed the rdj-shatts-forrealthistime branch 2 times, most recently from c5a697c to df1d953 Compare July 7, 2025 21:28

This comment has been minimized.

Sign in to view

aDotInTheVoid commented Jul 7, 2025

View reviewed changes

This comment has been minimized.

Sign in to view

rust-cloud-vms bot force-pushed the rdj-shatts-forrealthistime branch from d772cf6 to 244351c Compare July 7, 2025 22:30

obi1kenobi reviewed Jul 8, 2025

View reviewed changes

		// NoMangle is special cased, as it's currently the only structured
		// attribute that we want to appear in HTML output.

	AK::Deprecation { .. } => return None, // Handled seperatly into Item::deprecation.
	AK::Deprecation { .. } => return None, // Handled separately into Item::deprecation.

	/// An attribute, eg `#[repr(C)]`
	/// An attribute, e.g. `#[repr(C)]`

		/// Things here are explicitly not covered by the [`FORMAT_VERSION`]
		/// constant, and may change without bumping the format version.

rustdoc-json: Structured attributes #142936

Are you sure you want to change the base?

rustdoc-json: Structured attributes #142936

Conversation

aDotInTheVoid commented Jun 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

rustbot commented Jun 23, 2025

Uh oh!

rustbot commented Jun 23, 2025

Uh oh!

jdonszelmann commented Jun 23, 2025

Uh oh!

This comment has been minimized.

obi1kenobi left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

bors commented Jun 24, 2025

Uh oh!

Uh oh!

rustbot commented Jun 24, 2025

Uh oh!

rustbot commented Jun 24, 2025

Uh oh!

aDotInTheVoid commented Jun 24, 2025

Uh oh!

This comment has been minimized.

obi1kenobi left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

GuillaumeGomez left a comment

Choose a reason for hiding this comment

Uh oh!

bors commented Jun 27, 2025

Uh oh!

This comment has been minimized.

Choose a reason for hiding this comment

Uh oh!

This comment has been minimized.

aDotInTheVoid commented Jul 7, 2025

Uh oh!

obi1kenobi left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

aDotInTheVoid commented Jun 23, 2025 •

edited

Loading

obi1kenobi left a comment •

edited

Loading