Repository navigation
Consider mangling ID's in rustdoc-json #91609
Description
Currently JSON ID's are (approximatly) the underling DefId's which means they are not realy opaque, despite what we've said in the RFC.
They happen to be the compiler internal DefId for that item, but in the JSON blob they should be treated as opaque as they aren't guaranteed to be stable across compiler invocations
The problem with this is that their is no obligation to treet the ID's as opaque (for a concreet example see scrabsha/scrabsha.github.io#2). If we want to garentee our ability to change the ID format, we should make it so that no one relies on the specific values of ID's by making them not cary information. Eg 0:0 lets the user know things, wheras a3aefbcbf31fa0bc12b9a73bc9d67976 (md5 hash) doesnt.
Potential Drawbacks
- Non determinism
- Harder to debug
- Slower to build
- Larger output
Which of these are actualy a problem, or just unfounded concerns I'm not sure:
If you want to change this: heres the places to look:
rust/src/librustdoc/json/mod.rs
Line 219 in 0fb1c37
rust/src/librustdoc/json/conversions.rs
Line 183 in 0fb1c37
I'm not sure if this is a good idea, and would love feedback
@rustbot modify labels: +C-discussion +A-rustdoc-json
Activity
camelid commentedon Dec 13, 2021
MD5 hashes should be deterministic, so non-determinism would only be introduced if we used a random number generator.
CraftSpider commentedon Jan 12, 2022
I think MD5 hashes would be okay, though I would also support simply encoding the output in a less 'human readable' way. I'm okay with information being conveyed, if it's more obvious that the user isn't meant to access/rely on that information (think base64 or such)
[-]Consider mangaling ID's in rustdoc-json[/-][+]Consider mangling ID's in rustdoc-json[/+]aDotInTheVoid commentedon May 14, 2024
Found an example of someone parsing the ID format in the wild:
https://github.com/zjp-CN/term-rustdoc/blob/6559ededa253e822c946fa6a2123ad55de7f82a8/tests/parse-json-docs/main.rs#L329-L368
aDotInTheVoid commentedon May 14, 2024
CC @zjp-CN. If there's information that's only availible by parsing the (supposed-to-be) opaque identifiers, I'd love to hear that. Otherwise just be aware that you're relying on an implementation detail, and it's liable to break without notice.
zjp-CN commentedon May 15, 2024
Hi, I did try to parse an id to learn about what it means in the testing, but haven't depended on it much in the app.
There is missing information on parsing type: rustdoc_types::Impl doesn't tell if it's an auto impl, whereas an id starting with
acan just tell it is.Rollup merge of rust-lang#125130 - aDotInTheVoid:id-docs, r=Guillaume…
Unrolled build for rust-lang#125130
zjp-CN commentedon Apr 20, 2025
Looks like this is not a problem now, since #130078 has landed.