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.

Sign up for GitHub

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

Jump to bottom

rustdoc-json: Document why Id can't just be DefId #133780

Closed
aDotInTheVoid opened this issue Dec 3, 2024 · 0 comments · Fixed by #133981
Closed

rustdoc-json: Document why Id can't just be DefId #133780

aDotInTheVoid opened this issue Dec 3, 2024 · 0 comments · Fixed by #133981
Assignees
@aDotInTheVoid
Labels
A-contributor-roadblock Area: Makes things more difficult for new or seasoned contributors to Rust A-docs Area: Documentation for any part of the project, including the compiler, standard library, and tools A-rustdoc-json Area: Rustdoc JSON backend C-enhancement Category: An issue proposing an enhancement or a PR with one. T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue.

Comments

@aDotInTheVoid
Copy link
Member

NIT: This comment could be more useful. The problem it's actually trying to solve is that a single pub use with 1 defid can expand to multiple rustdoc-json items it the name exists in multiple namespaces: https://godbolt.org/z/jEnGxoWx6.

At some point in the future, we should maybe change how we do this on the JSON side, but not in this PR.

Originally posted by @aDotInTheVoid in #130078 (comment)

Rustdoc-json's Id handling is a bit subtle. There should be a nice doc-comment to explain it.

It came up on zulip here
@rustbot rustbot added the needs-triage This issue may need triage. Remove it if it has been sufficiently triaged. label Dec 3, 2024
@aDotInTheVoid aDotInTheVoid added T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue. A-contributor-roadblock Area: Makes things more difficult for new or seasoned contributors to Rust A-rustdoc-json Area: Rustdoc JSON backend and removed needs-triage This issue may need triage. Remove it if it has been sufficiently triaged. labels Dec 3, 2024
@aDotInTheVoid aDotInTheVoid self-assigned this Dec 3, 2024
@fmease fmease added C-enhancement Category: An issue proposing an enhancement or a PR with one. A-docs Area: Documentation for any part of the project, including the compiler, standard library, and tools labels Dec 6, 2024
@aDotInTheVoid aDotInTheVoid mentioned this issue Dec 6, 2024
Merged
matthiaskrgr added a commit to matthiaskrgr/rust that referenced this issue Mar 13, 2025
@matthiaskrgr
Rollup merge of rust-lang#133981 - aDotInTheVoid:document-docs-ids, r…
65c1eef 
…=fmease

rustdoc-json: Refractor and document Id's

Closes rust-lang#133780

While working on documenting Id's, I realized alot of the way they were generated was weird and unnecessary. Eg:

1. The fully uninterned id type was `(FullItemId, Option<FullItemId>)`, meaning it wasn't actually full!
2. None of the extra fields in `Option<FullItemId>` would ever be used
3. `imported_item_id` was a `rustdoc_json_types::Id` instead of a simpler `DefId`.

I believe the new implementation still covers all the same cases, but in a more principled way (and explaining why each piece is needed).

This was written to be reviewed commit-by-commit, but it might be easier to review all at once if you're not interested in tracking how the original code became the final code.

cc `@its-the-shrimp`

r? `@fmease`
@bors bors closed this as completed in b3ab695 Mar 13, 2025
rust-timer added a commit to rust-lang-ci/rust that referenced this issue Mar 13, 2025
@rust-timer
Unrolled build for rust-lang#133981
26ec318 
Rollup merge of rust-lang#133981 - aDotInTheVoid:document-docs-ids, r=fmease

rustdoc-json: Refractor and document Id's

Closes rust-lang#133780

While working on documenting Id's, I realized alot of the way they were generated was weird and unnecessary. Eg:

1. The fully uninterned id type was `(FullItemId, Option<FullItemId>)`, meaning it wasn't actually full!
2. None of the extra fields in `Option<FullItemId>` would ever be used
3. `imported_item_id` was a `rustdoc_json_types::Id` instead of a simpler `DefId`.

I believe the new implementation still covers all the same cases, but in a more principled way (and explaining why each piece is needed).

This was written to be reviewed commit-by-commit, but it might be easier to review all at once if you're not interested in tracking how the original code became the final code.

cc ``@its-the-shrimp``

r? ``@fmease``
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees

@aDotInTheVoid aDotInTheVoid

Labels
A-contributor-roadblock Area: Makes things more difficult for new or seasoned contributors to Rust A-docs Area: Documentation for any part of the project, including the compiler, standard library, and tools A-rustdoc-json Area: Rustdoc JSON backend C-enhancement Category: An issue proposing an enhancement or a PR with one. T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue.
Projects
None yet
Milestone
No milestone
Development

Successfully merging a pull request may close this issue.

rustdoc-json: Refractor and document Id's aDotInTheVoid/rust
3 participants
@fmease @aDotInTheVoid @rustbot