Skip to content
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

make precise capturing args in rustdoc Json typed #138109

Merged
merged 1 commit into from
Mar 13, 2025

Conversation

Kohei316
Copy link
Contributor

@Kohei316 Kohei316 commented Mar 6, 2025

close #137616

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
Copy link
Collaborator

rustbot commented Mar 6, 2025

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 rustbot added A-rustdoc-json Area: Rustdoc JSON backend A-rustdoc-search Area: Rustdoc's search feature S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. T-compiler Relevant to the compiler team, which will review and decide on the PR/issue. T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue. T-rustdoc-frontend Relevant to the rustdoc-frontend team, which will review and decide on the web UI/UX output. labels Mar 6, 2025
@rustbot
Copy link
Collaborator

rustbot commented Mar 6, 2025

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

Copy link
Member

@obi1kenobi obi1kenobi left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Comment on lines 248 to 252
impl clean::PreciseCapturingArg {
fn print(&self) -> impl Display + '_ {
self.name().as_str()
}
}
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

(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.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Comment on lines 936 to 943
/// A non-lifetime argument such as a generic parameter or a constant parameter.
Param(String),
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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!

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

@Kohei316 Kohei316 force-pushed the feat/rust-doc-precise-capturing-arg branch from d2c79a6 to 9ece166 Compare March 6, 2025 17:30
@aDotInTheVoid 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 aDotInTheVoid added the F-precise_capturing `#![feature(precise_capturing)]` label Mar 8, 2025
Copy link
Member

@aDotInTheVoid aDotInTheVoid left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

//@ 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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

NIT: This isn't needed after #137955

}

impl PreciseCapturingArg {
pub(crate) fn name(&self) -> &Symbol {
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

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

/// One precise capturing argument.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

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

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We should give an example here, eg:

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

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

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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
Copy link
Member

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

@compiler-errors compiler-errors self-assigned this Mar 8, 2025
@rustbot 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. 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
@rustbot

This comment has been minimized.

@Kohei316 Kohei316 force-pushed the feat/rust-doc-precise-capturing-arg branch from bbe63cb to dc894e7 Compare March 8, 2025 15:38
@rustbot 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 Kohei316 force-pushed the feat/rust-doc-precise-capturing-arg branch from dc894e7 to 3e1927c Compare March 9, 2025 07:50
@bors 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 10, 2025
jieyouxu added a commit to jieyouxu/rust that referenced this pull request Mar 10, 2025
…turing-arg, r=aDotInTheVoid,compiler-errors

make precise capturing args in rustdoc Json typed

close rust-lang#137616

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`.
jieyouxu added a commit to jieyouxu/rust that referenced this pull request Mar 10, 2025
…turing-arg, r=aDotInTheVoid,compiler-errors

make precise capturing args in rustdoc Json typed

close rust-lang#137616

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`.
jieyouxu added a commit to jieyouxu/rust that referenced this pull request Mar 11, 2025
…turing-arg, r=aDotInTheVoid,compiler-errors

make precise capturing args in rustdoc Json typed

close rust-lang#137616

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`.
bors added a commit to rust-lang-ci/rust that referenced this pull request Mar 11, 2025
Rollup of 16 pull requests

Successful merges:

 - rust-lang#126856 (remove deprecated tool `rls`)
 - rust-lang#136932 (Reduce formatting `width` and `precision` to 16 bits)
 - rust-lang#137314 (change definitely unproductive cycles to error)
 - rust-lang#137612 (Update bootstrap to edition 2024)
 - rust-lang#138002 (Disable CFI for weakly linked syscalls)
 - rust-lang#138052 (strip `-Wlinker-messages` wrappers from `rust-lld` rmake test)
 - rust-lang#138063 (Improve `-Zunpretty=hir` for parsed attrs)
 - rust-lang#138109 (make precise capturing args in rustdoc Json typed)
 - rust-lang#138147 (Add maintainers for powerpc64le-unknown-linux-gnu)
 - rust-lang#138245 (stabilize `ci_rustc_if_unchanged_logic` test for local environments)
 - rust-lang#138296 (Remove `AdtFlags::IS_ANONYMOUS` and `Copy`/`Clone` condition for anonymous ADT)
 - rust-lang#138300 (add tracking issue for unqualified_local_imports)
 - rust-lang#138307 (Allow specifying glob patterns for try jobs)
 - rust-lang#138313 (Update books)
 - rust-lang#138315 (use next_back() instead of last() on DoubleEndedIterator)
 - rust-lang#138318 (Rustdoc: remove a bunch of `@ts-expect-error` from main.js)

r? `@ghost`
`@rustbot` modify labels: rollup
jieyouxu added a commit to jieyouxu/rust that referenced this pull request Mar 11, 2025
…turing-arg, r=aDotInTheVoid,compiler-errors

make precise capturing args in rustdoc Json typed

close rust-lang#137616

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`.
bors added a commit to rust-lang-ci/rust that referenced this pull request Mar 11, 2025
Rollup of 18 pull requests

Successful merges:

 - rust-lang#126856 (remove deprecated tool `rls`)
 - rust-lang#137314 (change definitely unproductive cycles to error)
 - rust-lang#137504 (Move methods from Map to TyCtxt, part 4.)
 - rust-lang#137701 (Convert `ShardedHashMap` to use `hashbrown::HashTable`)
 - rust-lang#137967 ([AIX] Fix hangs during testing)
 - rust-lang#138002 (Disable CFI for weakly linked syscalls)
 - rust-lang#138052 (strip `-Wlinker-messages` wrappers from `rust-lld` rmake test)
 - rust-lang#138063 (Improve `-Zunpretty=hir` for parsed attrs)
 - rust-lang#138109 (make precise capturing args in rustdoc Json typed)
 - rust-lang#138147 (Add maintainers for powerpc64le-unknown-linux-gnu)
 - rust-lang#138245 (stabilize `ci_rustc_if_unchanged_logic` test for local environments)
 - rust-lang#138296 (Remove `AdtFlags::IS_ANONYMOUS` and `Copy`/`Clone` condition for anonymous ADT)
 - rust-lang#138300 (add tracking issue for unqualified_local_imports)
 - rust-lang#138307 (Allow specifying glob patterns for try jobs)
 - rust-lang#138313 (Update books)
 - rust-lang#138315 (use next_back() instead of last() on DoubleEndedIterator)
 - rust-lang#138318 (Rustdoc: remove a bunch of `@ts-expect-error` from main.js)
 - rust-lang#138330 (Remove unnecessary `[lints.rust]` sections.)

Failed merges:

 - rust-lang#137147 (Add exclude to config.toml)

r? `@ghost`
`@rustbot` modify labels: rollup
jieyouxu added a commit to jieyouxu/rust that referenced this pull request Mar 12, 2025
…turing-arg, r=aDotInTheVoid,compiler-errors

make precise capturing args in rustdoc Json typed

close rust-lang#137616

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`.
jieyouxu added a commit to jieyouxu/rust that referenced this pull request Mar 12, 2025
…turing-arg, r=aDotInTheVoid,compiler-errors

make precise capturing args in rustdoc Json typed

close rust-lang#137616

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`.
bors added a commit to rust-lang-ci/rust that referenced this pull request Mar 12, 2025
Rollup of 25 pull requests

Successful merges:

 - rust-lang#134076 (Stabilize `std::io::ErrorKind::InvalidFilename`)
 - rust-lang#136842 (Add libstd support for Trusty targets)
 - rust-lang#137314 (change definitely unproductive cycles to error)
 - rust-lang#137504 (Move methods from Map to TyCtxt, part 4.)
 - rust-lang#137621 (Add std support to cygwin target)
 - rust-lang#137701 (Convert `ShardedHashMap` to use `hashbrown::HashTable`)
 - rust-lang#138109 (make precise capturing args in rustdoc Json typed)
 - rust-lang#138161 (Add PeekMut::refresh)
 - rust-lang#138162 (Update the standard library to Rust 2024)
 - rust-lang#138174 (Elaborate trait assumption in `receiver_is_dispatchable`)
 - rust-lang#138175 (Support rmeta inputs for --crate-type=bin --emit=obj)
 - rust-lang#138269 (uefi: fs: Implement FileType, FilePermissions and FileAttr)
 - rust-lang#138313 (Update books)
 - rust-lang#138318 (Rustdoc: remove a bunch of `@ts-expect-error` from main.js)
 - rust-lang#138331 (Use `RUSTC_LINT_FLAGS` more)
 - rust-lang#138333 (Rebuild llvm spuriously less frequently)
 - rust-lang#138343 (Enable `f16` tests for `powf`)
 - rust-lang#138345 (Some autodiff cleanups)
 - rust-lang#138346 (naked functions: on windows emit `.endef` without the symbol name)
 - rust-lang#138347 (Reduce `kw::Empty` usage, part 2)
 - rust-lang#138360 (Fix false-positive in `expr_or_init` and in the `invalid_from_utf8` lint)
 - rust-lang#138371 (Update compiletest's `has_asm_support` to match rustc)
 - rust-lang#138372 (Refactor `pick2_mut` & `pick3_mut` to use `get_disjoint_mut`)
 - rust-lang#138376 (Item-related cleanups)
 - rust-lang#138377 (Remove unnecessary lifetime from `PatInfo`.)

r? `@ghost`
`@rustbot` modify labels: rollup
matthiaskrgr added a commit to matthiaskrgr/rust that referenced this pull request Mar 13, 2025
…turing-arg, r=aDotInTheVoid,compiler-errors

make precise capturing args in rustdoc Json typed

close rust-lang#137616

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`.
matthiaskrgr added a commit to matthiaskrgr/rust that referenced this pull request Mar 13, 2025
…turing-arg, r=aDotInTheVoid,compiler-errors

make precise capturing args in rustdoc Json typed

close rust-lang#137616

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`.
bors added a commit to rust-lang-ci/rust that referenced this pull request Mar 13, 2025
…iaskrgr

Rollup of 7 pull requests

Successful merges:

 - rust-lang#137816 (attempt to support `BinaryFormat::Xcoff` in `naked_asm!`)
 - rust-lang#138109 (make precise capturing args in rustdoc Json typed)
 - rust-lang#138343 (Enable `f16` tests for `powf`)
 - rust-lang#138356 (bump libc to 0.2.171 to fix xous)
 - rust-lang#138371 (Update compiletest's `has_asm_support` to match rustc)
 - rust-lang#138380 (ci: add runners for vanilla LLVM 20)
 - rust-lang#138404 (Cleanup sysroot locating a bit)

r? `@ghost`
`@rustbot` modify labels: rollup
bors added a commit to rust-lang-ci/rust that referenced this pull request Mar 13, 2025
…iaskrgr

Rollup of 6 pull requests

Successful merges:

 - rust-lang#137816 (attempt to support `BinaryFormat::Xcoff` in `naked_asm!`)
 - rust-lang#138109 (make precise capturing args in rustdoc Json typed)
 - rust-lang#138343 (Enable `f16` tests for `powf`)
 - rust-lang#138356 (bump libc to 0.2.171 to fix xous)
 - rust-lang#138371 (Update compiletest's `has_asm_support` to match rustc)
 - rust-lang#138404 (Cleanup sysroot locating a bit)

r? `@ghost`
`@rustbot` modify labels: rollup
@bors bors merged commit 1a7d2b9 into rust-lang:master Mar 13, 2025
6 checks passed
@rustbot rustbot added this to the 1.87.0 milestone Mar 13, 2025
rust-timer added a commit to rust-lang-ci/rust that referenced this pull request Mar 13, 2025
Rollup merge of rust-lang#138109 - Kohei316:feat/rust-doc-precise-capturing-arg, r=aDotInTheVoid,compiler-errors

make precise capturing args in rustdoc Json typed

close rust-lang#137616

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`.
github-actions bot pushed a commit to model-checking/verify-rust-std that referenced this pull request Mar 14, 2025
…iaskrgr

Rollup of 6 pull requests

Successful merges:

 - rust-lang#137816 (attempt to support `BinaryFormat::Xcoff` in `naked_asm!`)
 - rust-lang#138109 (make precise capturing args in rustdoc Json typed)
 - rust-lang#138343 (Enable `f16` tests for `powf`)
 - rust-lang#138356 (bump libc to 0.2.171 to fix xous)
 - rust-lang#138371 (Update compiletest's `has_asm_support` to match rustc)
 - rust-lang#138404 (Cleanup sysroot locating a bit)

r? `@ghost`
`@rustbot` modify labels: rollup
@Kohei316 Kohei316 deleted the feat/rust-doc-precise-capturing-arg branch March 15, 2025 06:32
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
A-rustdoc-json Area: Rustdoc JSON backend A-rustdoc-search Area: Rustdoc's search feature F-precise_capturing `#![feature(precise_capturing)]` S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. T-compiler Relevant to the compiler team, which will review and decide on the PR/issue. T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue. T-rustdoc-frontend Relevant to the rustdoc-frontend team, which will review and decide on the web UI/UX output.
Projects
None yet
Development

Successfully merging this pull request may close these issues.

rustdoc-json: Precise capturing JSON is untyped
7 participants