Add a way to signal that a snippet is UB/bad in rustdoc

[Izzeri]

Reading the docs for MaybeUninit I noticed that the code snippets that contain code that lead to UB are only identified by comments inside the snippet. This feels like a potential source of copy-paste errors. Maybe there could be a way to highlight a code snippet in a bright red or something to make readers wary that this code should never be used?

[Centril]

Sounds like a nice idea!

cc @RalfJung

[RalfJung]

Yes, I like it. :)

We do mark them no_run. But that does not seem to be reflected in any way.

[17cupsofcoffee]

The Rust book handles this by tinting the background of the code sample red and displaying an icon in the top corner: https://doc.rust-lang.org/book/ch02-00-guessing-game-tutorial.html#comparing-the-guess-to-the-secret-number

[RalfJung]

That's for things that don't compile though, not for things that compile but cause UB.

[17cupsofcoffee]

Yeah, it's not exactly the same thing (although they also use the same sort of formatting for code that panics/exhibits undesirable behaviour, which is a bit closer) - just thought it was a good example of what this kind of feature could look like.

[GuillaumeGomez]

Normally, it's up to the person writing the doc to precise such a thing. I'm afraid that if we add it, some code blocks that should have it will have it, but a lot others won't have it. And since doc readers will be used to see this UI element for this kind of code blocks, they won't pay attention and then troubles will start.

Not sure if I was clear enough?

[RalfJung]

@GuillaumeGomez I do not follow your reasoning. Are you saying that better marking code as UB will lead to people paying less attention to that marker? That seems very unplausible to me. How would someone who pays so little attention that they ignore a fat red warning light, not be much likely to ignore the comments and surrounding text that we currently have?

Of course documentation demonstrating UB still has to explain where exactly the UB arises and why. None of this can go away, and I do not think it will. The goal of this marker is to make sure that a quick reader who does not pay attention, does not read the surrounding text nor the comments -- that they are less likely to copy-paste this pattern.

[GuillaumeGomez]

@GuillaumeGomez I do not follow your reasoning. Are you saying that better marking code as UB will lead to people paying less attention to that marker? That seems very unplausible to me. How would someone who pays so little attention that they ignore a fat red warning light, not be much likely to ignore the comments and surrounding text that we currently have?

No, the opposite. Some examples that should have it will certainly not have it (for whatever reasons, such things happen) and users won't pay attention and just use it as is since they don't see this visual marker.

Of course documentation demonstrating UB still has to explain where exactly the UB arises and why. None of this can go away, and I do not think it will. The goal of this marker is to make sure that a quick reader who does not pay attention, does not read the surrounding text nor the comments -- that they are less likely to copy-paste this pattern.

Which makes the situation worse in case a code blocks that should have this marker doesn't have it like I said above.

[RalfJung]

I understand.

I see your concern, but I find it a strange argument against more explicit marks. We have documentation of varying quality across the ecosystem, and you are suggesting to reduce the quality of libstd documentation for the benefit of some crate that forgets to mark their UB example as UB.

[GuillaumeGomez]

No, not reducing libstd documentation quality. For the moment, we say what examples are invalid/incorrect. Adding this feature (which is a nice one, even though I think it might a bit too much) would just increase the gap between the libstd quality and the rust ecosystem. Also, it'd be very complicated to test that an example is indeed invalid alongside the updates.

Anyway, I'm just afraid that adding this feature wouldn't improve global rust ecosystem quality but instead drop it.