Inconsistently documented constraints for IntoIterator::Item

[cuviper]

The documentation for IntoIterator is inconsistent in how it shows the Item constraints.

The actual trait declaration looks like this:

pub trait IntoIterator {
    type Item;
    type IntoIter: Iterator<Item = Self::Item>;
    fn into_iter(self) -> Self::IntoIter;
}

The nightly core documentation matches this declaration as of 1.49.0-nightly (3525087 2020-10-08). This is good.

However, the nightly std documentation shows no Item constraints at all:

pub trait IntoIterator {
    type Item;
    type IntoIter: Iterator;
    fn into_iter(self) -> Self::IntoIter;
}

The std documentation for 1.48.0-beta.2 is even weirder, using an equality constraint that's not supported (#20041), and this goes all the way back to 1.0.0.

pub trait IntoIterator
where
    <Self::IntoIter as Iterator>::Item == Self::Item,
{
    type Item;
    type IntoIter: Iterator;
    fn into_iter(self) -> Self::IntoIter;
}

[jyn514]

This is the relevant code for traits:

rust/src/librustdoc/html/render/mod.rs

Line 2433 in c9a48d1

"{}{}{}trait {}{}{}",

This is the relevant code for trait bounds:

rust/src/librustdoc/html/format.rs

Line 154 in c9a48d1

crate fn print_generic_bounds(bounds: &[clean::GenericBound]) -> impl fmt::Display + '_ {

After that it goes into Ty::print() and I'm not sure where it goes.

rust/src/librustdoc/html/format.rs

Line 352 in c9a48d1

write!(f, "{}", self.trait_.print())

[jyn514]

Well. I think I found the issue.

rust/src/librustdoc/html/format.rs

Lines 846 to 847 in c9a48d1

	// FIXME: `param_names` are not rendered, and this seems bad?
	drop(param_names);

[jyn514]

Hmm, changing that didn't help - it's always None, at least when documenting IntoIterator.

[jyn514]

The bounds passed to print_generic_bounds are incorrect across crates. Here they are for the original crate:

2:rustcDEBUG rustdoc::html::format printing bounds [TraitBound(PolyTrait { trait_: ResolvedPath { path: Path { global: false, res: Def(Trait, DefId(2:5285)), segments: [PathSegment { name: "Iterator", args: AngleBracketed { args: [], bindings: [TypeBinding { name: "Item", kind: Equality { ty: QPath { name: "Item", self_type: Generic("Self"), trait_: ResolvedPath { path: Path { global: false, res: Def(Trait, DefId(0:3)), segments: [] }, param_names: None, did: DefId(0:3), is_generic: false } } } }] } }] }, param_names: None, did: DefId(2:5285), is_generic: false }, generic_params: [] }, None)]

and for the re-export:

2:rustcDEBUG rustdoc::html::format printing bounds [TraitBound(PolyTrait { trait_: ResolvedPath { path: Path { global: false, res: Err, segments: [PathSegment { name: "Iterator", args: AngleBracketed { args: [], bindings: [] } }] }, param_names: None, did: DefId(2:5285), is_generic: false }, generic_params: [] }, None)]

In particular note that bindings is completely empty.

[jyn514]

This looks like the culprit:

rust/src/librustdoc/clean/mod.rs

Lines 1598 to 1609 in c9a48d1

	ty::Foreign(did) => {
	inline::record_extern_fqn(cx, did, TypeKind::Foreign);
	let path = external_path(
	cx,
	cx.tcx.item_name(did),
	None,
	false,
	vec![],
	InternalSubsts::empty(),
	);
	ResolvedPath { path, param_names: None, did, is_generic: false }
	}

vec![] is the bindings.

[jyn514]

This needs larger refactors to rustdoc than I'm comfortable making. bindings is Vec<TypeBinding>, but the only way to construct those is through

rust/src/librustdoc/clean/mod.rs

Line 2408 in c9a48d1

impl Clean<TypeBinding> for hir::TypeBinding<'_> {

which works on the hir, not DefIds, and the HIR is not preserved across crates.

Maybe @GuillaumeGomez is interested in refactoring this? ;)

[fmease]

Update: The current nightly output is still incorrect:

pub trait IntoIterator {
    type Item;
    type IntoIter: Iterator
    where
        <Self::IntoIter as Iterator>::Item == Self::Item;

    fn into_iter(self) -> Self::IntoIter;
}

I am already working on a fix and I have already assigned myself to the duplicates of this issue (#84579 and #102142).
@rustbot claim

[GuillaumeGomez]

Awesome, thanks!