Tracking issue for normalizing (evaluating) types in rustdoc-generated docs (-Z normalize-docs)

[jyn514]

This is a tracking issue for the rustdoc feature -Z normalize-docs. This normalizes projections like <Vec<T> as IntoIterator>::IntoIter to std::vec::IntoIter<T> in the generated documentation.

About tracking issues

Tracking issues are used to record the overall progress of implementation.
They are also used as hubs connecting to other relevant issues, e.g., bugs or open design questions.
A tracking issue is however not meant for large scale discussion, questions, or bug reports about a feature.
Instead, open a dedicated issue for the specific matter and add the relevant feature gate label.

Steps

• Implement the features (Normalize <X as Y>::T for rustdoc #77467)
• Fix the bugs blocking stabilization (Move reporting recursion limit errors outside of the trait system #81091)
  • Cycles in trait bounds should be recoverable (Rustdoc regression (overflow evaluating the requirement …) #79459): Make cycle errors recoverable #102037
  • Recursion limit errors in trait bounds should be recoverable (nightly rustdoc reaches recursion limit while beta works fine #79506)
• Stabilization PR (see instructions on rustc-dev-guide)

Unresolved Questions

No unresolved questions known, this is "just hard".

Implementation history

• initial impl: Normalize <X as Y>::T for rustdoc #77467
• reverted due to breakage: Revert "Normalize <X as Y>::T for rustdoc" #79469
• re-added as unstable: Add -Z normalize-docs and enable it for compiler docs #79525

[fmease]

Apart from marking the impl as S-tracking-impl-incomplete Status: The implementation is incomplete. / “incomplete” (buggy), I'm marking it as S-tracking-design-concerns Status: There are blocking design concerns. because there have been lots of discussions around the question whether we want to normalize/evaluate constant expressions in rustdoc at all¹ (“intent” vs. “representation”) and by extension the same concern applies to types. See #102456, #99630, Zulip discussion.

Footnotes

1. Or rather only if the corresponding item was marked with a new attribute. ↩

[fmease]

In rust-lang/rfcs#3770 (review) I just wrote:

---

[…]

1. A subgroup of users would like rustdoc to normalize types. Type normalization almost became the default (Normalize <X as Y>::T for rustdoc #77467) but due to limitations of the current (but not next-gen) trait solver (namely: fatal overflows), it had to be gated behind the -Znormalize-docs where this behavior currently resides. Also, rustdoc is notoriously bad at properly tracking binders (think higher-ranked lifetimes). It's gotten better but it's not sufficient (cc use ObligationCtxt not QueryNormalizer in rustdoc's normalization  #108503).
2. A subgroup of users would like public type aliases to remain unexpanded and private ones to be folded away. This is what rustdoc currently does for items of the local crate. Infamously, this does not extend to inlined cross-crate re-exports (rustdoc: reexported type aliases are not preserved in function signatures #15823) as they use a different IR (middle IR vs HIR). This has created the multi-year effort of representing type aliases in the "type/trait system IR" (aka middle::ty). See Tracking issue for lazy type aliases #112792.

However, [1] (type normalization) is inherently incompatible with [2] (public type alias preservation). I'm currently driving [2] and will block any attempt at stabilizing [1] :P (not that there was any push to do so). This screams "we'd like to have configuration".