rustdoc: fix & clean up handling of cross-crate higher-ranked parameters

[fmease]

Preparatory work for the refactoring planned in #113015 (for correctness & maintainability).

---

1. Render the higher-ranked parameters of cross-crate function pointer types (*).
2. Replace occurrences of collect_referenced_late_bound_regions() (CRLBR) with bound_vars().
   The former is quite problematic and the use of the latter allows us to yank a lot of hacky code (†)
   as you can tell from the diff! :)
3. Add support for cross-crate higher-ranked type parameters (#![feature(non_lifetime_binders)]).
   We were previously ICE'ing on them (see inline_cross/non_lifetime_binders.rs).

---

(*): Extracted from test inline_cross/fn-type.rs:

- fn(_: &'z fn(_: &'b str), _: &'a ()) -> &'a ()
+ for<'z, 'a, '_unused> fn(_: &'z for<'b> fn(_: &'b str), _: &'a ()) -> &'a ()

(†): It returns an FxHashSet which isn't predictable or stable wrt. source code (.rmeta) changes. To elaborate, the ordering of late-bound regions doesn't necessarily reflect the ordering found in the source code. It does seem to be stable across compilations but modifying the source code of the to-be-documented crates (like adding or renaming items) may result in a different order:

Example

Let's assume that we're documenting the cross-crate re-export of produce from the code below. On master, rustdoc would render the list of binders as for<'x, 'y, 'z>. However, once you add back the functions a–l, it would be rendered as for<'z, 'y, 'x> (reverse order)! Results may vary. bound_vars() fixes this as it returns them in source order.

// pub fn a() {}
// pub fn b() {}
// pub fn c() {}
// pub fn d() {}
// pub fn e() {}
// pub fn f() {}
// pub fn g() {}
// pub fn h() {}
// pub fn i() {}
// pub fn j() {}
// pub fn k() {}
// pub fn l() {}

pub fn produce() -> impl for<'x, 'y, 'z> Trait<'z, 'y, 'x> {}

pub trait Trait<'a, 'b, 'c> {}

impl Trait<'_, '_, '_> for () {}

Further, as the name suggests, CRLBR only collects referenced regions and thus we drop unused binders. bound_vars() contains unused binders on the other hand. Let's stay closer to the source where possible and keep unused binders.

Lastly, using bound_vars() allows us to get rid of

• the deduplication and alphabetical sorting hack in simplify.rs
• the weird field bound_params on EqPredicate

both of which were introduced by me in #102707 back when I didn't know better.

To illustrate, let's look at the cross-crate bound T: for<'a, 'b> Trait<A<'a> = (), B<'b> = ()>.

• With CRLBR + EqPredicate.bound_params, before bound simplification we would have the bounds T: Trait, for<'a> <T as Trait>::A<'a> == () and for<'b> <T as Trait>::B<'b> == () which required us to merge for<>, for<'a> and for<'b> into for<'a, 'b> in a deterministic predictable manner and without introducing duplicate binders.
• With bound_vars(), we now have the bounds for<'a, b> T: Trait, <T as Trait>::A<'a> == () and <T as Trait>::B<'b> == () before bound simplification similar to rustc itself. This obviously no longer requires any funny merging of for<>s. On top of that for<'a, 'b> is guaranteed to be in source order.

[rustbot]

r? @notriddle

(rustbot has picked a reviewer for you, use r? to override)

[rustbot]

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

cc @camelid

[fmease]

Theoretically, I could make this generic by letting it take a <T> bound_ty: ty::Binder<'tcx, T> instead but I've decided against it for simplicity and to avoid code size explosion due to excessive monomorphization. I could use a non-generic inner function though, if you'd like.

[notriddle]

I'm happy with this function not being generic. It wouldn't save very much code at the call site if it was.

[fmease]

This change allows us to render the for<> parameter list of cross-crate fn ptr tys.

[notriddle]

If nothing else, I'm glad to see all this duplicate code factored out into a function. ❤️

[notriddle]

I'm happy with this function not being generic. It wouldn't save very much code at the call site if it was.

[notriddle]

Does anybody know what kind of code would motivate fixing this? Is it actually possible to make rustdoc misrender something because the outer and inner binders aren't being merged?

[fmease]

I'm not super familiar with some of the details surrounding bound vars yet. I can't tell you all possible cases where the type and the signature have bound vars at the same time.

I can give you one example though which rustdoc renders just fine:

pub fn f(_: impl for<'a> Trait<for<'b> fn(&'a (), &'b ())>) {  }
pub trait Trait<T> {}

Here, bound_ty.bound_vars() is ['a] and sig.bound_vars() is ['b]. It would be incorrect to concatenate ['a] and ['b]. We don't want to render for<'a> … for<'a, 'b> fn(…).

In this case, the bound_ty.bound_vars() is ['a] because clean_poly_trait_ref_with_bindings passes this list of bound vars down to external_path to … to ty_args_to_args which calls clean_middle_ty. I'm not sure if that's the intended usage of map_bound but I guess it is since oli-obk implemented that as far as I know.
bound_ty.skip_binder() and just using sig.bound_vars() should therefore be fine.

[fmease]

In my limited understanding, I disagree with the FIXME, it would be super odd to merge different binder lists, rustc does it like one or two times in exceptional cases. There can be a semantic difference between for<'a> … for<'b> … and for<'a, 'b> … and rustc needs to shift the de Bruijn indices and the var indices for correctness after merging such lists.

A few months ago, I chatted a bit with compiler-errors about ty::Binder<_> and bound vars in rustdoc and from what I've learned rustdoc (still) doesn't properly track bound vars. This was relevant for #112463 where we don't have enough information to be able to deal with (escaping) late bound vars. I haven't understood everything yet and thus my explanation sucks.

I'm pretty sure from what I've learned so far, proper bound var handling would prevent ICEs in rustdoc like in PR #108503 (which you're acquainted with) and probably other ones like https://github.com/rust-lang/rust/issues?q=is%3Aissue+is%3Aopen+label%3AT-rustdoc%20label%3AI-ICE%20label%3AA-auto-traits%20label%3AA-synthetic-impls.

[notriddle]

That makes sense.

@bors r+ rollup

[bors]

📌 Commit ace85f0 has been approved by notriddle

It is now in the queue for this repository.