rustdoc: Document lack of object safety on affected traits

[poliorcetics]

Closes #85138

I saw the issue didn't have any recent activity, if there is another MR for it I missed it.

I want the issue to move forward so here is my proposition.

It takes some space just before the "Implementors" section and only if the trait is not object
safe since it is the only case where special care must be taken in some cases and this has the
benefit of avoiding generation of HTML in (I hope) the common case.

[rustbot]

r? @jsha

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

[rustbot]

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

cc @camelid

[poliorcetics]

[fmease]

Thanks! Please add object-safety to the list of IDs in file src/librustdoc/html/markdown.rs, function init_id_map.

[GuillaumeGomez]

Since it's making UI changes, let's start an FCP.

@rfcbot fcp start

[GuillaumeGomez]

Wrong command...

@rfcbot fcp merge

[rfcbot]

Team member @GuillaumeGomez has proposed to merge this. The next step is review by the rest of the tagged team members:

• @GuillaumeGomez
• @Manishearth
• @Nemo157
• @aDotInTheVoid
• @camelid
• @jsha
• @notriddle

No concerns currently listed.

Once a majority of reviewers approve (and at most 2 approvals are outstanding), this will enter its final comment period. If you spot a major issue that hasn't been raised at any point in this process, please speak up!

See this document for info about what commands tagged team members can give me.

[poliorcetics]

By the way if someone better versed in it can confirm I made the section & link accessible it would be nice, I don't know what is needed for this

[poliorcetics]

@Nemo157 I think this PR is only waiting for review/approval, if you have the time

[GuillaumeGomez]

Soory, I completely missed this FCP when I was filling the agenda. I added it in the rustdoc agenda to be discussed next meeting if it hasn't been approved until then.

[rfcbot]

The final comment period, with a disposition to merge, as per the review above, is now complete.

As the automated representative of the governance process, I would like to thank the author for their work and everyone else who contributed.

This will be merged soon.

[GuillaumeGomez]

Thanks for the improvement!

@bors r+ rollup

[bors]

📌 Commit a119158 has been approved by GuillaumeGomez

It is now in the queue for this repository.

[obi1kenobi]

Would it be possible to expose this data in rustdoc JSON as well?

It would be very useful to cargo-semver-checks, since object safety is public API and upholding it is a tricky semver hazard.

[GuillaumeGomez]

Sure.

[obi1kenobi]

Thank you! 🚀

Another thing that would be super useful to have (it would unlock many new lints) is knowing whether a trait is sealed or not. This is not currently shown in either HTML or JSON output. In theory it is possible to compute given sufficient rustdoc JSONs (including the stdlib), but it's quite hard to do since we don't have all of the compiler's infrastructure available and there are so many different ways to seal a trait (partial list here).

[GuillaumeGomez]

So a trait that has a requirement for a local trait (based on this blog post). One question I have is: if the required private trait has a blanket impl, is the trait still sealed?

[obi1kenobi]

One question I have is: if the required private trait has a blanket impl, is the trait still sealed?

The trait is still sealed if the blanket impl has a bound on a trait that is itself sealed. Otherwise, it is not sealed -- it can be impl'd outside its defining crate.

So a trait that has a requirement for a local trait (based on this blog post).

There are a few more ways to make a trait not implementable outside its crate. I believe this to be an exhaustive list:

• if the trait has a sealed supertrait (sealed in any way, not just pub-in-priv)
• if the trait has a "sealed method" without a default impl, in any of the ways that allow sealing a method:
  • a pub-in-priv type as a parameter or return type (described here)
  • a sealed trait as a bound (described here)
• if the trait has an associated type with a sealed trait as a bound
• if the trait has an associated const of a pub-in-priv type that doesn't have a default

This is why it's so hard to determine whether a trait is sealed or not without all the compiler machinery being present 😅

[GuillaumeGomez]

Sounds like it would be quite tricky to check. However I think the information would be important to have. Can you open a new issue so the rustdoc team can discuss about it please? (With all the explanations too :) )

[Nemo157]

https://rust-lang.github.io/rfcs/3323-restrictions.html adds native syntax for sealed traits, it might be better to only support that (which will presumably be carried into the rustdoc-json somehow) and just require users of the existing hacks to migrate (which should be non-breaking, other than MSRV).

[obi1kenobi]

Opened #119280 with more precise descriptions of when a trait is sealed.

To be honest, even if that RFC were to become available on stable tomorrow, I don't expect users of the existing approaches will migrate anytime soon. The linked issue has details, but TL;DR maintainers have minimal incentive to change code that from their perspective 100% works fine just to adopt a new syntax.