[rustdoc-json] absolute position of item is hard to get

[Urgau]

Problem:
Currently, the only way to accurately (see #93522 for reason why paths is not accurate) know the position of an item is to traverse all modules and items down to the item that we want, this is costly and inefficient especially for Ids that comes from the documentation (ie intra-doc-links) because they can link to outside.

Solution:
Have a parent_id field that link the current Item to it's direct parent. This would mean that we could go from down (item) to upper (module) in a straightforward way.

[Enselic]

It is not quite that simple unfortunately, because an item can have many "parents". Consider this code insrc/lib.rs:

mod m {
    pub const C: usize = 7;
}

pub mod a {
    pub use super::m::C;
}

pub mod b {
    pub use super::m::C;
}

The rustdoc JSON will be (some details omitted):

        "0:4": {
            "id": "0:4",
            "crate_id": 0,
            "name": "C",
            "visibility": "public",
            "kind": "constant",
            "inner": {
                "type": {
                    "kind": "primitive",
                    "inner": "usize"
                },
            }
        },
        "0:5": {
            "id": "0:5",
            "crate_id": 0,
            "name": "a",
            "visibility": "public",
            "kind": "module",
            "inner": {
                "is_crate": false,
                "items": [
                    "0:4"           <--- Note: Contains C
                ]
            }
        },
        "0:9": {
            "id": "0:9",
            "crate_id": 0,
            "name": "b",
            "visibility": "public",
            "kind": "module",
            "inner": {
                "is_crate": false,
                "items": [
                    "0:4"           <--- Note: Also contains C
                ]
            }
        },

So if you were to encounter only "0:4", you would not know what parent is "correct".

[Urgau]

It is not quite that simple unfortunately, because an item can have many "parents".

Yes many relative "parents" but there is only one absolute parent. Ex: a struct A is defined in the module my_mod with a re-export from a another module, in this case the parent of A is my_mod and nothing else.
Here parent should be seeing as where the item was defined. A item can only be defined in one place and so can only have one parent.

[Enselic]

What you call the "absolute parent" is not always present in the rustdoc JSON output though. For example in the sample code above, because mod m is not pub. I use this command: RUSTDOCFLAGS='-Z unstable-options --output-format json' cargo +nightly doc --lib --no-deps.

Should we simply omit parent_id in that case? That doesn't seem quite right either.

[Urgau]

What you call the "absolute parent" is not always present in the rustdoc JSON output though.

This will solved by #93518 who is introducing the StrippedModule item.

I have already been locally experimenting with #93518 and DefIdTree::parent, and it seems to work (decently) well. I will continue to experiment/test to see the all up and downside.