Consider indicating which code blocks are expected to compile and which are not in the guide(s)

[huonw]

It can be a little unclear when a code block is not meant to compile (there's occasionally a question in IRC about "a piece of code from the guide doesn't compile" because the asker didn't realise it's meant to be an example illustrating a compiler error) so we could do something to make it more obvious, e.g. coloured borders:

[rustonaut]

I agree on this the question is how to link it with the automated doc generation.

Maybe adding a green border for examples run by doc test. And add some differentiation between tests witch does not run because they are "codesnipeds" (yellow) and this witch are negative examples (redly grayed out text?)

In general there should be as little negative examples as possible and we should pay attention that the "this does not work" mark is not confused with a ”important look here" mark by new comers

[shepmaster]

👍 This also creates Stack Overflow questions.

[huonw]

It's worth noting that using only a coloured border here is not very accessible: if something like this is added, we should strongly consider adding accessibility hints/ARIA at the same time, or even using an alternative scheme entirely.

[rustonaut]

@huonw: I agree it should be made accessible for everyone. I have no experience with aria and screen reader (sounds really helpful) but I think a possible approach would be

• add color markings
• change the visual so that colorblind people can see it*
• add more ARIA accessibility features, e.g. for screen readers
• maybe make some pull featured on the Forum+Weekly Rust Newsletter to decide between multiple possible ways to implement the previous steps

In regard to 3 for negative running examples we might add "a line of ! or X or???" parallel/instead of the straight line featured above e.g.:

X |     let x: u32 = 888i64;
X |     println!("{}", x);

or a zigzag line but not sure if there is a good way to implement this in css.

For code snippets we could consider adding some kind of marker at the top+bottom of the snipped to indicate that "there is more" similar to ellipses in a text. E.g. in gnome3 there is that stripped line at the top/bottom if you can scroll up/down (just as a example, not sure if that would work four this case)

Oh and this is a bit far stretched, but for negative examples witch run as doctest with should_panic or witch can't compile it might be possible to record the run-time/compiler error, and in case of a compiler error do some simple error highlighting in the shown code and maybe add some way to blend in the error message. But well that seems to be a lot of work an another attribute additional to ignore would be needed like should_not_compile (Through such a mechanism might also be useful to test restrictions through the type system in unit-tests).

[kzys]

Resolving? We have merged #44397 and #44927 last year :)

[shepmaster]

The original post concerned the book (now generated by mdbook), not the output of rustdoc.

A demo of rustdoc output from Rust 1.29.0:

Since mdbook is in a different repo, I think it's OK to close this. Ping me if you disagree!