rustdoc: Show whether generic type params actually are `?Sized`, not whether definition site syntactically includes `?Sized`

[obi1kenobi]

Code

?Sized is unlike other bounds: while T: Foo demands that T implement Foo, T: ?Sized allows T to not be Sized — it does not demand it. It relaxes an obligation, that's it.

If that obligation is demanded by another clause, then adding ?Sized has no effect. For example:

trait Private: Sized {}

pub fn example<T: Private + ?Sized>(value: &T) {}

Here T: Private and Private: Sized imply T: Sized, so T: ?Sized has no effect. This is confirmed by clippy, which raises a needless_maybe_sized lint here.

Since rustdoc is a tool for documenting the public API of Rust programs, I believe that it is misleading and undesirable for it to report T: ?Sized in circumstances where unsized types will not be accepted. It doesn't matter if the definition site of the generic type parameter syntactically mentions T: ?Sized if that clause has no effect on the public API.

Reproduction Steps

cargo doc for HTML output.

RUSTDOCFLAGS="-Z unstable-options --output-format=json --cap-lints=allow" cargo doc for JSON output.

Expected Outcome

Observe pub fn example<T: Private>(value: &T) as the recorded function signature in HTML docs. T: ?Sized does not apply to the API in practice, so it is excluded.

By the same reasoning, do not include T: ?Sized as a trait bound in rustdoc JSON.

Actual Output

Observe pub fn example<T: Private + ?Sized>(value: &T) as the recorded function signature in HTML docs.

Observe the following item in rustdoc JSON:

{
    "id": 0,
    "crate_id": 0,
    "name": "example",
    "span": {
        // omitted for brevity
    },
    "visibility": "public",
    "docs": null,
    "links": {},
    "attrs": [],
    "deprecation": null,
    "inner": {
        "function": {
            "sig": {
                // omitted for brevity
            },
            "generics": {
                "params": [
                    {
                        "name": "T",
                        "kind": {
                            "type": {
                                "bounds": [
                                    {
                                        "trait_bound": {
                                            "trait": {
                                                "path": "Private",
                                                "id": 1,
                                                "args": {
                                                    "angle_bracketed": {
                                                        "args": [],
                                                        "constraints": []
                                                    }
                                                }
                                            },
                                            "generic_params": [],
                                            "modifier": "none"
                                        }
                                    },
                                    {
                                        "trait_bound": {
                                            "trait": {
                                                "path": "Sized",
                                                "id": 2,
                                                "args": {
                                                    "angle_bracketed": {
                                                        "args": [],
                                                        "constraints": []
                                                    }
                                                }
                                            },
                                            "generic_params": [],
                                            "modifier": "maybe"  // <-- `?Sized`
                                        }
                                    }
                                ],
                                "default": null,
                                "is_synthetic": false
                            }
                        }
                    }
                ],
                "where_predicates": []
            },
            // omitted for brevity
        }
    }
}

Version

rustc 1.90.0-nightly (28f1c8079 2025-06-24)
binary: rustc
commit-hash: 28f1c807911c63f08d98e7b468cfcf15a441e34b
commit-date: 2025-06-24
host: x86_64-unknown-linux-gnu
release: 1.90.0-nightly
LLVM version: 20.1.7

@rustbot label +A-rustdoc-json

[fmease]

I think we want to take a step back and think about the overall goals and promises of rjson — speaking as someone who's not super involved in it presently but who has spent hours upon hours since 2022 fixing and extending the cleaning/resugaring routines that try to reconstruct the middle IR back into Rust's surface syntax¹ for rhtml².

It seems to me that you/CSC would like rjson to be incredibly rich in information (see previous proposals: implied bounds, elaborated bounds, variances (incl. "traces"), layout info) — ideally everything rustc has gained in its analysis steps — which is a reasonable ask. Basically that's the middle IR + its queries for you (concrete example that's directly relevant to this issue: the notion of relaxed bounds ("?Sized") doesn't exist in that IR, they have been lowered away already).

So under the assumption that CSC was the only rjson consumer, it appears advantageous for rjson to shift gears and — instead of cleaning HIR + a bit of middle IR — pipe middle IR directly to the JSON serializer without any postprocessing³ (clarification: if we were to keep operating on the HIR for rjson and enrich it with the aforementioned pieces of info, it would mean that rustdoc would had to replicate (i.e., duplicate code) and duplicate (i.e., redo what's already been computed) several analysis steps which I'm very much against). The question becomes: Is that a reasonable thing to do in the eyes of all rjson consumers/stakeholders? Personally speaking I don't know, maybe?

I'm curious if you have looked at stable MIR? It basically mirrors the middle IR + its queries 100%. I must admit that I haven't read the AllHands meeting notes about rjson vs. stable MIR yet.

Since it's hard to convey tone in writing, I want to clarify that this shouldn't be read as an attack (?) or declaration of frustration (?) but simply as a non-judgemental listing of thoughts and questions by someone who is still somewhat confused about the role of rjson.

Footnotes

1. E.g., eliding generic parameter defaults and object lifetime defaults, reconstructing relaxed bounds ("?Sized") and assoc item equality constraints. ↩

2. Granted, in rjson my past work is only visible in the synthetic blanket and auto trait impls since apparently rjson doesn't inline cross-crate re-exports. ↩

3. OTOH you expressed a desire for rustdoc to compute specific extra information (e.g., "traces" of variances), so CSC doesn't need to do it. That makes sense in the context of CSC but it's not really scalable to arbitrary consumers/stakeholders ("if everyone asks for specific thing X to be included, then ..."). ↩

[fmease]

cc @aDotInTheVoid

[obi1kenobi]

Thanks for the reply — the points are very reasonable and worth discussing.

Overall, I do think that there are valid cases where c-s-c would be better served by more direct access to HIR or MIR or both. A good example is the variance trace info you mentioned, which is probably not that useful to the average rustdoc JSON consumer and probably shouldn't be added there. Stable MIR is something I'm very curious about but isn't an immediate priority right now, since my focus is largely on "what lints should even exist" and "how do we enable cross-crate analysis" and stable MIR isn't part of either of those conversations.

But for issues like this one, the implied bounds one, and the layout info (especially on e.g. #[repr(C)] pub types and their pub fields), I don't think those are questions specific to c-s-c in any way. The goal of rustdoc is in the name, right? We're documenting the public API — and the public API here is not about whether ?Sized appears syntactically, but whether a downstream user actually can or cannot use an unsized type in that parameter's position.

So I would consider adding accurate ?Sized information, implied bounds, and layout info to rustdoc HTML an improvement per se, even if we completely ignore c-s-c's needs. If we continue ignoring c-s-c entirely, the parallel JSON API argument would be "it should at least contain the same info that's in the HTML" which still seems pretty reasonable to me.

In the long run, I think it would make a lot of sense to discuss more direct ways to pipe rustc analysis info into c-s-c. But I suspect right now we'd be best served by waiting on that:

• Depending on how stable MIR goes, that might end up being a major part of the answer — even though c-s-c wasn't a motivating use case for it.
• There's plenty of c-s-c work to do (at least another 6-12 months) that won't run into the limits of where we really need to dig into HIR / MIR etc. For example: cross-crate lints, type-checking lints, witnesses, a lot of perf work, and probably another ~100 lints over data rustdoc JSON either already contains or definitely will (e.g. field default values, whenever those are stabilized).

Lmk what you think! I'd be happy to hop on a video call if discussing this more interactively would be helpful — like you said, tone is hard to convey in writing :)