rustdoc-json: Rename Path::name to path, and give it the path again.

[aDotInTheVoid]

Closes: #135600.

Reverts #134880 (Effectively, but not actually, as the FORMAT_VERSION needs to be bumped, changed docs/tests). CC @AS1100K.

Also CC @obi1kenobi @LukeMathWalker

Still needs before being merge-ready:

• Tests for cross-crate paths
• (Maybe) Document what the field does.
• Decide if the field rename is good (rustdoc-json: Rename Path::name to path, and give it the path again. #135799 (comment))
• Squash commits.

r? @GuillaumeGomez

[obi1kenobi]

Thank you for putting this together! 🙏

[obi1kenobi]

Suggested change

	// Check we only have paths for structs at there origonal path
	// Check we only have paths for structs at their original path

[AS1100K]

Thanks for this PR! A revert was necessary because we need to prevent #134880 from being included in the beta, as it would break tools and we cannot change paths.path from absolute path to public facing path because it is required for generating source URLs by rustdoc and other crates.

[aDotInTheVoid]

A revert was necessary because we need to prevent #134880 from being included in the beta, as it would break tools

N.B: Rustdoc-Json is currently unstable, and not usable on beta/stable. The purpose of the revert is to fix nightly.

we cannot change paths.path from absolute path to public facing path because it is required for generating source URLs by rustdoc and other crates.

I’m not sure i follow.

[LukeMathWalker]

I don't follow the last part either—rustdoc's HTML backend doesn't build on top of the JSON output AFAIK. Even if it did, it doesn't expose private paths for public items.

[AS1100K]

we cannot change paths.path from absolute path to public facing path because it is required for generating source URLs by rustdoc and other crates.

Sorry, I wasn't clear. What I meant was

For the code:

#![no_std]

pub type Foo = core::str::SplitAsciiWhitespace<'static>;

The json output will be

{
  "index": {
    "0": {
      "id": 0,
      "inner": {
        "type_alias": {
          "generics": {"params": [], "where_predicates": []},
          "type": {
            "resolved_path": {
              "args": {"angle_bracketed": {"args": [{"lifetime": "'static"}], "constraints": []}},
              "id": 1,
              "name": "SplitAsciiWhitespace"
            }
          }
        }
      },
      "name": "Foo"
    },
    "2": {
      "id": 2,
      "inner": {"module": {"is_crate": true, "is_stripped": false, "items": [0]}},
      "name": "mcve"
    }
  },
  "paths": {
    "0": {"crate_id": 0, "kind": "type_alias", "path": ["mcve", "Foo"]},
    "1": {"crate_id": 1, "kind": "struct", "path": ["core", "str", "iter", "SplitAsciiWhitespace"]}
  },
  "root": 2
}

Here, "path": ["core", "str", "iter", "SplitAsciiWhitespace"] was refered as path.path. I said it because this field is in ItemSummary struct which is constructed from Cache here which is used by HTML backend to get the absolute path i.e. "core", "str", "iter", "SplitAsciiWhitespace" as per above example to get the URL for source file that would be core/str/iter.rs.html and I thought of replacing this path with public facing path that would be core::str::SplitAsciiWhitespace but then thought absolute path could also be important for other libaries (like i am building cargo-wiki) to use this absolute path to generate URL on docs.rs or some other mechanism they might want.

I hope I made it clear but if not please ask me, I might be wrong so please let me know.

[aDotInTheVoid]

rustdoc's HTML backend doesn't build on top of the JSON output AFAIK.

Correct, both of them built of clean, a rustdoc internal IR (that's in turn built from HIR & MIR)

as per above example to get the URL for source file that would be ...

For source URL's, rustdoc-html goes through the Span infrastructure (as should rustdoc-json consumers): See https://github.com/rust-lang/rust/blob/ed43cbcb882e7c06870abdd9305dc1f17eb9bab9/src/librustdoc/html/sources.rs for details.

---

The issue is that paths comes from an implementation detail of HTML (see #93522), so it's kinda arbitrary what's there. As some point it'll need to be properly thought through (possibly alongside the long-awaited cross-crate id solution.

[aDotInTheVoid]

A though while doing the docs: Should this field be renamed to not name? Having name: String actually be a path seems really surprising and goofy. How'd people feel about it being path instead?

[rustbot]

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

[aDotInTheVoid]

@GuillaumeGomez the code can be reviewed as-is, it's ready. But don't merge it yet, I want to squash commits before that. (But don't want to yet, incase we decide to not do the field rename, as it'd be easier to revert).

[LukeMathWalker]

A though while doing the docs: Should this field be renamed to not name? Having name: String actually be a path seems really surprising and goofy. How'd people feel about it being path instead?

It'd definitely be a better match for what it currently contains. It works for me.

[obi1kenobi]

Suggestion, feel free to take it or leave it: I'm not 100% sure what "used" means in this context. Is it the path referenced in the code being documented, either directly or via an import? AKA "what path would we have to remove to break the code being documented"

Perhaps an example could help?

[aDotInTheVoid]

Added an example:

pub type Vec1 = std::vec::Vec<i32>; // path: "std::vec::Vec"
pub type Vec2 = Vec<i32>; // path: "Vec"
pub type Vec3 = std::prelude::v1::Vec<i32>; // path: "std::prelude::v1::Vec"

[obi1kenobi]

Thank you!

[aDotInTheVoid]

Docs improved. Commits squashed.

[obi1kenobi]

Looks good to me, thank you! Seems ready to merge, if I'm not mistaken?

I'm eager to use it in cargo-semver-checks ASAP, so that we narrow the window of nightlies with which we're incompatible :)

[GuillaumeGomez]

I already approve so it's up to @aDotInTheVoid whenever they want. :)

[aDotInTheVoid]

@bors r=GuillaumeGomez rollup

(Sorry, I didn't realize github's green check meant r=you here. I don't think there's a norm here)

[bors]

📌 Commit 9c0e32b has been approved by GuillaumeGomez

It is now in the queue for this repository.

[GuillaumeGomez]

Ah sorry, miscommunication I think. You said you wanted my approval but not my merge because you wanted to make another small change. So I approved and for me it was all done. Should have precised. ^^'