rustdoc-json: Document the `blanket_impl` field

[obi1kenobi]

The blanket_impl field on Impl is currently undocumented, and has strange & possibly-buggy behavior.

Consider the following code:

#![feature(no_core)]
#![no_core]

pub trait Example {}

impl<T> Example for T {}

Generating rustdoc JSON for it produces the following entry for the impl item:

{
    "id": 1,
    "crate_id": 0,
    "name": null,
    "span": {
        "filename": "src/lib.rs",
        "begin": [
            6,
            0
        ],
        "end": [
            6,
            24
        ]
    },
    "visibility": "default",
    "docs": null,
    "links": {},
    "attrs": [],
    "deprecation": null,
    "inner": {
        "impl": {
            "is_unsafe": false,
            "generics": {
                "params": [
                    {
                        "name": "T",
                        "kind": {
                            "type": {
                                "bounds": [],
                                "default": null,
                                "is_synthetic": false
                            }
                        }
                    }
                ],
                "where_predicates": []
            },
            "provided_trait_methods": [],
            "trait": {
                "path": "Example",
                "id": 0,
                "args": {
                    "angle_bracketed": {
                        "args": [],
                        "constraints": []
                    }
                }
            },
            "for": {
                "generic": "T"
            },
            "items": [],
            "is_negative": false,
            "is_synthetic": false,
            "blanket_impl": null
        }
    }
}

Unless I've drastically misunderstood some terminology, this impl is a blanket impl, and yet blanket_impl is empty.

I find this surprising. I would have expected

"blanket_impl": {
    "generic": "T"
}

since that's the type over which the blanket impl applies.

Hypothetically if the impl were instead impl<T> Example for Vec<T>, I'm not sure whether blanket_impl should then be None or correspond to Vec<T>. It would be great to document this choice explicitly.

This isn't high priority for me — I have a workaround. Just flagging it for completeness and on the off chance that I might be misunderstanding what that field is meant to do.

Meta

rustc --version --verbose:

rustc 1.86.0-nightly (f027438f8 2025-02-03)
binary: rustc
commit-hash: f027438f8bc6b747528dca8b8de13043544d7238
commit-date: 2025-02-03
host: x86_64-unknown-linux-gnu
release: 1.86.0-nightly
LLVM version: 19.1.7

[compiler-errors]

There's no bug here. Blanket impls -- in rustdoc -- are the synthetic impls that rustdoc deduces for things like auto traits. This is a user-written impl, so it's never considered to be a blanket.

[obi1kenobi]

Ah, got it. In that case, let's tag this as a documentation issue instead of a bug.

@rustbot label -C-bug +A-docs +A-rustdoc-json

[compiler-errors]

I was mistaken, actually -- blanket impls are two things:

1. Blanket impls impls that we synthesize for certain types (structs/enums/etc) that do not have a "rigid" type constructor. In type parlance, that means that they have generic self type.
2. For each rigid type we are documenting, like a struct, we synthesize copies of blanket impls for each struct. The layout of these blanket impls is a bit strang. If I document a crate containing a single struct like:

pub struct Foo;

I end up getting, for example, a blanket Any impl (since Any is in core upstream) that looks like:

{
    "id": 38,
    "crate_id": 0,
    "name": null,
    "span": {
        "filename": "/home/mgx/rust/library/core/src/any.rs",
        "begin": [
            138,
            0
        ],
        "end": [
            138,
            35
        ]
    },
    "visibility": "default",
    "docs": null,
    "links": {},
    "attrs": [],
    "deprecation": null,
    "inner": {
        "impl": {
            "is_unsafe": false,
            "generics": {
                "params": [
                    {
                        "name": "T",
                        "kind": {
                            "type": {
                                "bounds": [],
                                "default": null,
                                "is_synthetic": false
                            }
                        }
                    }
                ],
                "where_predicates": [
                    {
                        "bound_predicate": {
                            "type": {
                                "generic": "T"
                            },
                            "bounds": [
                                {
                                    "outlives": "'static"
                                },
                                {
                                    "trait_bound": {
                                        "trait": {
                                            "path": "Sized",
                                            "id": 15,
                                            "args": {
                                                "angle_bracketed": {
                                                    "args": [],
                                                    "constraints": []
                                                }
                                            }
                                        },
                                        "generic_params": [],
                                        "modifier": "maybe"
                                    }
                                }
                            ],
                            "generic_params": []
                        }
                    }
                ]
            },
            "provided_trait_methods": [],
            "trait": {
                "path": "Any",
                "id": 39,
                "args": {
                    "angle_bracketed": {
                        "args": [],
                        "constraints": []
                    }
                }
            },
            "for": {
                "resolved_path": {
                    "path": "Foo",
                    "id": 0,
                    "args": {
                        "angle_bracketed": {
                            "args": [],
                            "constraints": []
                        }
                    }
                }
            },
            "items": [
                36
            ],
            "is_negative": false,
            "is_synthetic": false,
            "blanket_impl": {
                "generic": "T"
            }
        }
    }
}

If we were to read this impl literally, it would look like:

impl<T: Sized + 'static> Any for Foo {}

... which is obviously wrong. However, when rendering the impl for html rustdoc, we use that "blanket impl" field to plug back in the "correct" self type:

rust/src/librustdoc/html/format.rs

Lines 1320 to 1324 in bef3c3b

	if let Some(ty) = self.kind.as_blanket_ty() {
	fmt_type(ty, f, use_absolute, cx)?;
	} else {
	self.print_type(&self.for_, f, use_absolute, cx)?;
	}

I expect this behavior implemented today exists as a side-effect of the way that rustdoc rendering occurs, where we use the wrong (i.e. substituted) self type to ensure that the impl gets sorted into struct Foo's set of impls.

[obi1kenobi]

Ah, I see — so blanket_impl is actually "what type was the impl literally on" whereas for is "what type does it apply to here". That makes sense, and it would be lovely to have it documented as such.

I didn't quite understand the "rigid type constructor" case, and I'd love an example if you have one handy, or a pointer to a quick primer to enough type theory so I might get up to speed.

Small typo fix suggestion: I think the reconstructed impl code example should read impl<T: ?Sized + 'static> Any for Foo {}, noting the ?Sized due to "modifier": "maybe".

[compiler-errors]

Well, I think "blanket_impl" is an implementation detail field of html rustdoc and shouldn't make its way to rustdoc-json at all, or it should at least be flipped with the "for_" field when these impls are being cleaned into their json representations.

Otherwise, unless every usage of the impl by consumers of rustdoc json knows to prefer using the "blanket_impl" field if it's set rather than "for_", then these impls are definitely not going to be correct for usage.

I hope it's clearly obvious that impl<T: Sized + 'static> Any for Foo {} is nonsense here -- it's just the impl blanket impl, copied, but with the wrong self type plugged in. Not substituted (i.e. replacing the trait ref with T = Foo), but literally just replaced with the self type of the type we're synthesizing the blanket impl for:

rust/src/librustdoc/clean/blanket_impl.rs

Lines 105 to 110 in bef3c3b

	for_: clean_middle_ty(
	ty::Binder::dummy(ty.instantiate_identity()),
	cx,
	None,
	None,
	),

didn't quite understand the "rigid type constructor" case, and I'd love an example if you have one handy, or a pointer to a quick primer to enough type theory so I might get up to speed.

It's the types that return none from this function in InstantiateWithInfer mode: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/ty/fast_reject/fn.simplify_type.html

[obi1kenobi]

I'm agnostic as to the exact fix applied here, and I am happy to make it work in cargo-semver-checks either way so long as the docs are clear on the field meanings and the possible edge cases :)

I'd love to just make sure that we can tell which type related to Foo is used as the T in the impl: for example, is it Foo or &mut Foo or dyn Foo?

I'm afraid I'm not familiar with rustc type-checking internals, so the InstantiateWithInfer example didn't stick for me =/ Is it possible to write a piece of Rust code that demonstrates that case? Only if you think it's a good use of time to do so, of course.