rustdoc: normalise type/field names

[its-the-shrimp]

Updates #100961

• Import -> Use, to better reflect the terminology of Rust & its syntax
• TypeBinding -> AssocItemConstraint, to sync up with clean
• FnDecl -> FunctionSignature, because that's what it is
• Header -> FunctionHeader, because Header is a very word that's very heavily loaded with different meanings
• ItemEnum::AssocType: default -> type, because those items appear in impl blocks as well, where they're not the "default"
• ItemEnum::AssocConst: default -> value, see the previous point
• ForeignType -> ExternType, because "foreign" is not the right word there
• boolean fields' names made to consistently be a phrase that can be a yes/no answer, e.g. async -> is_async

The docs of ItemEnum::AssocType::type_ & of ItemEnum::AssocConst::value are also updated to be up to date with the clarification of the name of the fields

[rustbot]

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]

Some changes occurred in src/librustdoc/clean/types.rs

cc @camelid

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

[its-the-shrimp]

r? @aDotInTheVoid

[camelid]

Hmm, some of this feels like unnecessary churn - particularly the changes to the boolean field names. For example, I don't think is_async is any clearer than async. I also don't see the point of renaming FnDecl since that's what it's called in rustc AFAICT. Curious what others think though.

[workingjubilee]

Hm. I agree is_async is not clearer than async but I think it is clearer than async_, which just looks like a typo. It's also just generally more annoying to have to work through serde-renames with JSON, because now you have more trouble finding the field in the source. Sure, the rename field itself will be highlighted in grep, but so will various other instances of the word "async" or "const"...

For TypeBinding -> AssocItemConstraint, it is probably important to make the change so that it does match what's in rustc.

I have no comment on the rest, though.

[compiler-errors]

I don't think Fn* to Function* is clearer. Naming it FnSig or FnDecl is kinda 🤷 though, but I don't think it necessarily makes sense to diverge from the HIR naming unless it's particularly more clear to call it a signature, which I don't think is true.

[fbstj]

#128667 (comment)

The reason for renaming FnDecl, and the whole PR in general, is to be more friendly to outside users, that might not be in the know about rustc conventions, a function declaration may be understood as fn printf(fmt: &str, ...);,even though what the FnDecl is there is actually just (fmt: &str, ...), which is universally understood to be a function signature

am I right in thinking that anyone using this output will know enough rust to relate the fn keyword to functions, and probably the Fn* traits.

[its-the-shrimp]

well, fn is a fundamental keyword in Rust, so fn <-> function is a trivial equality to expect the user to understand, the change from Fn to Function there is purely for consistency with the existing Function & FunctionPointer structures, I don't believe we should be swayed by rustc's naming in rustdoc-json, since rustc is definitely not intended to be public API, unlike rustdoc-json

[its-the-shrimp]

And the change from Decl to Signature is explained in my comment a bit below

[obi1kenobi]

I love the effort to use clearer and more consistent terminology, and document rustdoc JSON types more thoroughly! Thanks to everyone helping this along 🙏

If possible, I'd just ask that you double-check that the name changes didn't negatively affect the size of generated rustdoc JSON files, e.g. by making an enum discriminant string substantially longer than before.

cargo-semver-checks is used on some crates with as many as ~250k items (e.g. aws-sdk-ec2 or windows), and currently the rule of thumb for rustdoc JSON is ~1KB/item on average. When the JSON file is 250MB and we need to compare two of them to each other on CI-grade hardware, IO size and parsing time are a significant factor in overall runtime. I wouldn't ask to squeeze out every last byte — I'd just hope to avoid things like "added 10 extra bytes apiece in something that'll appear 250k times in the file" because that would be a measurable slowdown. To be clear, I don't think that's happened here, but I'd love to be extra sure.

[its-the-shrimp]

The reason for renaming FnDecl, and the whole PR in general, is to be more friendly to outside users, that might not be in the know about rustc conventions, a function declaration may be understood as fn printf(fmt: &str, ...);,even though what the FnDecl is there is actually just (fmt: &str, ...), which is universally understood to be a function signature

[its-the-shrimp]

regarding boolean fields, it's fine if we end up deciding to keep their names as they are, however, another reason for this PR was to close the question of naming in rustdoc-json (hence the "Fixes" annotation at the start), thus, I believe whatever renames we happen to decide on in this PR will serve as a precedent for naming conventions for rustdoc-json in the future (I believe @aDotInTheVoid wanted to document those conventions)

[bors]

☔ The latest upstream changes (presumably #128673) made this pull request unmergeable. Please resolve the merge conflicts.

[aDotInTheVoid]

While there's value for making all the JSON changes in one PR (we batch many small breaking changes into 1 large one), it's not a good idea for the clean types. If you want to make changes to them, they can be done in later, smaller PR's that just do one thing (so are easier to review).

[its-the-shrimp]

Should I revert the changes in jsondoclint as well?

[aDotInTheVoid]

Should I revert the changes in jsondoclint as well?

No, jsondoclint uses the types from rustdoc_json_types, so it will need to be changed.

[obi1kenobi]

While I am generally in favor of the renaming of what the fields are called in Rust, I am strongly opposed to the new longer field names in JSON.

I'd like to ask that we consider not introducing the is_ prefixes into the rustdoc JSON itself, to avoid bloating the file and causing perf regressions without any human-visible improvement.

The largest crate that uses cargo-semver-checks produces a 475MB rustdoc JSON file, and contains ~100k functions and ~400k trait and inherent impls. Deserializing that file is a measurable bottleneck in cargo-semver-checks — we deserialize two such files per run, and spend about 4-5s wall-clock on it.

The proposed changes in the JSON field names in this PR will increase the file size by about 3-4MB (~1%). There's no real offsetting benefit for this regression, since the JSON is primarily meant to be machine-readable — it isn't even pretty-printed by default. There's very little advantage to having more descriptive field names repeat thousands of times.

Let's please keep the JSON field names short?

[its-the-shrimp]

That's valid, I was also thinking about that, and I think there's a way to avoid the tug'o'war between the JSON & the Rust repr, which is having certain fields not serialised if they contain the "default" value whatever it happens to be, e.g. false for booleans, I think this will bring compression benefits that'll far outweigh any size increases brought by long field names

E.g.

#[serde(default)]#[serde(skip_serializing_if = "is_default")]// Function to be definedpub is_async: bool,

I'd be eager to implement this after this PR is merged

[obi1kenobi]

I'd love to have both default/omitted fields and short field names as much as possible!

475MB of rustdoc JSON is a lot, and the scary thing is that a year ago that crate "only" produced ~250MB of rustdoc JSON. I'm not sure how much of that is due to format changes vs growth in the crate, but it's not a trend we can sustain for long either way. Short field names are a cheap way to buy a few percent, and especially leaving JSON field names unchanged by only adding the is_ prefix in Rust not JSON feels like an easy win.

[its-the-shrimp]

@rustbot ready
I've also renamed the can_unwind field in Abi back to unwind to not have the name bring any assumptions about the technical details of the ABI by the word "can", and I've reverted all the changes in the HTML output of rustdoc

[its-the-shrimp]

@aDotInTheVoid what's your opinion on the changes to the boolean field names?

[aDotInTheVoid]

I think that if changing the field names to be longer causes a perf regression, that's a problem with the overall serialization/de-serialization strategy, not the type design. I'm strongly opposed to changing field names or using serde defaults to try to fix perf. I want to review this PR solely based on how good the names are.

I've opened a zulip thread to discuss potentially compressing or using alternative serialization formats for perf-sensitive users. Please don't have any further discussion around output sizes in this PR.

[aDotInTheVoid]

This looks really close, thanks for working on it, and sorry for the review delay.

r=me with field name renamed

[its-the-shrimp]

@bors r=@aDotInTheVoid

[bors]

@its-the-shrimp: 🔑 Insufficient privileges: Not in reviewers

[aDotInTheVoid]

@bors r+

Thanks so much for working on this!

[bors]

📌 Commit f2696ab has been approved by aDotInTheVoid

It is now in the queue for this repository.