rustdoc-json: Structured representation of attributes

[aDotInTheVoid]

Today, rustdoc-json presents attributes as a Vec<String>

rust/src/rustdoc-json-types/lib.rs

Lines 179 to 196 in 356f2d0

	/// Attributes on this item.
	///
	/// Does not include `#[deprecated]` attributes: see the [`Self::deprecation`] field instead.
	///
	/// Some attributes appear in pretty-printed Rust form, regardless of their formatting
	/// in the original source code. For example:
	/// - `#[non_exhaustive]` and `#[must_use]` are represented as themselves.
	/// - `#[no_mangle]` and `#[export_name]` are also represented as themselves.
	/// - `#[repr(C)]` and other reprs also appear as themselves,
	/// though potentially with a different order: e.g. `repr(i8, C)` may become `repr(C, i8)`.
	/// Multiple repr attributes on the same item may be combined into an equivalent single attr.
	///
	/// Other attributes may appear debug-printed. For example:
	/// - `#[inline]` becomes something similar to `#[attr="Inline(Hint)"]`.
	///
	/// As an internal implementation detail subject to change, this debug-printing format
	/// is currently equivalent to the HIR pretty-printing of parsed attributes.
	pub attrs: Vec<String>,

This means that users wanting to use these attributes (and not just display them) must implement a parser for these strings. It'd be nice if rustdoc exposed the semantics of the attribute, and not just the syntax.

This'd mean going from Vec<String> to Vec<Attr>, and adding some enum Attr with all the possible kinds of attribute. The exact details would require design work. See #137645 (comment) for more detail.

Possibly this should wait untill the state of rustc's own attribute system is more settled (#131229).

CC @jdonszelmann @obi1kenobi

[aDotInTheVoid]

This has a newfound urgency:

mhm, I messaged Alona today as well, since it's technically also a breaking change in rustdoc json. However, it's really annoying since I'll be making about a 100 separate breaking changes like this in the coming months.... and practically few people will care

Originally posted by @jdonszelmann in #138165 (comment)

A half-baked idea from someone who should be asleep: If we moved to a structured representation of attributes in rustdoc-json (#141358), we could say "Anything structured is guarded by FORMAT_VERSION, anything in the Other(String) is compiler debug output, and not stable". That way for the attributes we know people care about. (E.g. #[repr]), we defiantly defiantly won't break them. But if we change how #[rustc_const_promotable] is, that's much more eh.

That way, we do a much better job signposting the attributes that we actually supports (vs the current ~backroom understanding about what's important to CSC). We can also say something like "if you really on a attribute that's currently Attribute::Other, talk to us and we'll try to add a variant.

And when we add variants to rustdoc_json_types::Attribute, we can do a load in 1 PR, to avoid generated a load of format version churn.

Originally posted by @aDotInTheVoid in #138165 (comment)

[aDotInTheVoid]

For an idea of the things that are important to support initially

No, unfortunately we need many more. At minimum (probably not an exhaustive list): #[non_exhaustive], #[automatically_derived], #[must_use], #[doc(hidden)], #[deprecated], #[no_mangle] and #[export_name] (plus their new unsafe variants like #[unsafe(no_mangle)]) , #[repr(packed)], #[repr(C)], #[repr(transparent)], enum integer reprs like #[repr(i8)].

And also now #[target_feature]

Originally posted by @obi1kenobi in #137645