make precise capturing args in rustdoc Json typed #138109

Kohei316 · 2025-03-06T16:23:50Z

This PR includes below changes.

Add rustc_hir::PreciseCapturingArgKind which allows the query system to return a arg's data.
Add rustdoc::clean::types::PreciseCapturingArg and change to use it.
Add rustdoc-json-types::PreciseCapturingArg and change to use it.
Update tests/rustdoc-json/impl-trait-precise-capturing.rs.
Bump rustdoc_json_types::FORMAT_VERSION.

rustbot · 2025-03-06T16:23:55Z

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-03-06T16:23:58Z

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

obi1kenobi

Thanks for working to make rustdoc better! I'm a prospective user of this functionality, and had a couple of questions based on reading the code.

obi1kenobi · 2025-03-06T16:38:15Z

src/librustdoc/html/format.rs

+impl clean::PreciseCapturingArg {
+    fn print(&self) -> impl Display + '_ {
+        self.name().as_str()
+    }
+}


(I'm not T-rustdoc, just a curious bystander) I'm a bit surprised by this code. It doesn't match the "usual" function signature of the other print() functions here (it doesn't take the TyCtxt<'_> argument) and it also isn't just a direct impl Display for PreciseCapturingArg even though it could be with the current function signature.

This is just my curiosity speaking: I'd love to know your view on this design decision compared to those other two options.

Well I agree with the previous comment: why bother making a method and not just directly put .name().as_str() below?

Um in fact this code is wrong. I guess I was confused. I wil fix this.

obi1kenobi · 2025-03-06T16:38:20Z

src/rustdoc-json-types/lib.rs

+    /// A non-lifetime argument such as a generic parameter or a constant parameter.
+    Param(String),


Do we have the means to distinguish between generic type and constant here?

As a prospective consumer of this API via cargo-semver-checks, that distinction would be very useful!

This is not be realised with small code chage because generic type and constant aren't distinguished neither in AST nor in HIR.

That's fine, I can make do on my end then. Thank you!

aDotInTheVoid

Thanks for working on this!

rustdoc side looks mostly good, with a couple of small nitpicks.

I'm less confident on the rustc side, and would like someone else to take a look before merging, so CC @compiler-errors I guess.

aDotInTheVoid · 2025-03-08T00:00:23Z

tests/rustdoc-json/impl-trait-precise-capturing.rs

-//@ is "$.index[*][?(@.name=='hello')].inner.function.sig.output.impl_trait[1].use[0]" \"\'a\"
-//@ is "$.index[*][?(@.name=='hello')].inner.function.sig.output.impl_trait[1].use[1]" \"T\"
-//@ is "$.index[*][?(@.name=='hello')].inner.function.sig.output.impl_trait[1].use[2]" \"N\"
+// ignore-tidy-linelength


NIT: This isn't needed after #137955

aDotInTheVoid · 2025-03-08T00:06:09Z

src/librustdoc/clean/types.rs

+}
+
+impl PreciseCapturingArg {
+    pub(crate) fn name(&self) -> &Symbol {


NIT: Symbol is Copy, so should be returned by value here.

aDotInTheVoid · 2025-03-08T00:10:15Z

src/rustdoc-json-types/lib.rs

@@ -927,6 +927,16 @@ pub enum TraitBoundModifier {
    MaybeConst,
 }

+/// One precise capturing argument.


NIT: This should link to the docs on precise capturing.

aDotInTheVoid · 2025-03-08T00:12:20Z

src/rustdoc-json-types/lib.rs

+#[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum PreciseCapturingArg {
+    /// A lifetime.


We should give an example here, eg:

pub fn hello<'a, T, const N: usize>() -> impl Sized + use<'a, T, N> {} // ^^

aDotInTheVoid · 2025-03-08T00:17:00Z

src/rustdoc-json-types/lib.rs

+pub enum PreciseCapturingArg {
+    /// A lifetime.
+    Lifetime(String),
+    /// A non-lifetime argument such as a generic parameter or a constant parameter.


Saying "such as" here can be read to mean there are other options not listed. Also, a "generic parameter" could refer to a constant parameter. It's clearer (to me at least) to say something like "A type or constant parameter".

I also don't love the name, but can't think of anything better off the top of my head. Curious if types people have any better ideas here. It does feel like we're leaking the HIR implementation details in that we differentiate lifetime, but not type vs generic parameters here.

Also: An example here would be nice.

compiler-errors · 2025-03-08T00:23:36Z

Ya i took a look at it earlier but can take another look at it tomorrow when im not out lol

compiler-errors

Seems fine to me.

compiler-errors · 2025-03-06T18:26:57Z

compiler/rustc_metadata/src/rmeta/mod.rs

@@ -440,7 +441,7 @@ define_tables! {
    coerce_unsized_info: Table<DefIndex, LazyValue<ty::adjustment::CoerceUnsizedInfo>>,
    mir_const_qualif: Table<DefIndex, LazyValue<mir::ConstQualifs>>,
    rendered_const: Table<DefIndex, LazyValue<String>>,
-    rendered_precise_capturing_args: Table<DefIndex, LazyArray<Symbol>>,
+    rendered_precise_capturing_args: Table<DefIndex, LazyArray<PreciseCapturingArgKind<Symbol,Symbol>>>,


Suggested change

rendered_precise_capturing_args: Table<DefIndex, LazyArray<PreciseCapturingArgKind<Symbol,Symbol>>>,

rendered_precise_capturing_args: Table<DefIndex, LazyArray<PreciseCapturingArgKind<Symbol, Symbol>>>,

compiler-errors · 2025-03-09T20:40:05Z

src/librustdoc/clean/types.rs

+}
+
+impl PreciseCapturingArg {
+    pub(crate) fn name(&self) -> Symbol {


Suggested change

pub(crate) fn name(&self) -> Symbol {

pub(crate) fn name(self) -> Symbol {

aDotInTheVoid · 2025-03-08T00:27:51Z

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;


This is taking place at the same time as #137956, which also (currently) makes the 40->41 change. Once one of these merges, the other should rebase then bump again. See #94591 for details.

rustbot assigned GuillaumeGomez Mar 6, 2025

obi1kenobi reviewed Mar 6, 2025

View reviewed changes

Kohei316 force-pushed the feat/rust-doc-precise-capturing-arg branch from d2c79a6 to 9ece166 Compare March 6, 2025 17:30

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 7, 2025

aDotInTheVoid assigned aDotInTheVoid and unassigned GuillaumeGomez Mar 8, 2025

aDotInTheVoid added the F-precise_capturing `#![feature(precise_capturing)]` label Mar 8, 2025

aDotInTheVoid reviewed Mar 8, 2025

View reviewed changes

compiler-errors self-assigned this Mar 8, 2025

This was referenced Mar 8, 2025

Add RTN support to rustdoc #137956

Open

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

Open

This comment has been minimized.

Sign in to view

Kohei316 force-pushed the feat/rust-doc-precise-capturing-arg branch from bbe63cb to dc894e7 Compare March 8, 2025 15:38

rustbot removed has-merge-commits PR has merge commits, merge with caution. S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. labels Mar 8, 2025

Kohei316 force-pushed the feat/rust-doc-precise-capturing-arg branch from dc894e7 to 3e1927c Compare March 9, 2025 07:50

compiler-errors approved these changes Mar 9, 2025

View reviewed changes

aDotInTheVoid reviewed Mar 9, 2025

View reviewed changes

make precise capturing args in rustdoc Json typed

112f7b0

Kohei316 force-pushed the feat/rust-doc-precise-capturing-arg branch from 3e1927c to 112f7b0 Compare March 10, 2025 12:40

Kohei316 requested review from aDotInTheVoid and compiler-errors March 10, 2025 13:51

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

make precise capturing args in rustdoc Json typed #138109

make precise capturing args in rustdoc Json typed #138109

Kohei316 commented Mar 6, 2025

rustbot commented Mar 6, 2025

rustbot commented Mar 6, 2025

obi1kenobi left a comment

obi1kenobi Mar 6, 2025

GuillaumeGomez Mar 6, 2025

Kohei316 Mar 6, 2025

obi1kenobi Mar 6, 2025

Kohei316 Mar 6, 2025

obi1kenobi Mar 6, 2025

aDotInTheVoid left a comment

aDotInTheVoid Mar 8, 2025

aDotInTheVoid Mar 8, 2025

aDotInTheVoid Mar 8, 2025

aDotInTheVoid Mar 8, 2025

aDotInTheVoid Mar 8, 2025

compiler-errors commented Mar 8, 2025

This comment has been minimized.

compiler-errors left a comment

compiler-errors Mar 6, 2025

compiler-errors Mar 9, 2025

aDotInTheVoid Mar 8, 2025

		/// A non-lifetime argument such as a generic parameter or a constant parameter.
		Param(String),

	rendered_precise_capturing_args: Table<DefIndex, LazyArray<PreciseCapturingArgKind<Symbol,Symbol>>>,
	rendered_precise_capturing_args: Table<DefIndex, LazyArray<PreciseCapturingArgKind<Symbol, Symbol>>>,

	pub(crate) fn name(&self) -> Symbol {
	pub(crate) fn name(self) -> Symbol {

make precise capturing args in rustdoc Json typed #138109

Are you sure you want to change the base?

make precise capturing args in rustdoc Json typed #138109

Conversation

Kohei316 commented Mar 6, 2025

rustbot commented Mar 6, 2025

rustbot commented Mar 6, 2025

obi1kenobi left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

aDotInTheVoid left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

compiler-errors commented Mar 8, 2025

This comment has been minimized.

compiler-errors left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment