Warn more gently on ignored example code

[bluss]

Source code (rendered):

//! ```ignore
//! use itertools::Itertools;
//! ```

This renders with a warning triangle in the crate's docs. "Be careful when using this code, it's not being tested!"

Can we be more gentle with the warnings? This warning reflects badly on the crate, and we cast doubt on it that is unfounded. Any author that uses ignore probably knew why they did so.

In this case the warning is especially visible and unlucky, and the user can easily be confused, is "the code" referring to the whole crate?

[GuillaumeGomez]

We'll need to discuss it in the next team meeting.

[est31]

cc #44397 . I was totally okay with the previous behaviour and don't really like the new one either.

[steveklabnik]

So, this is one of the longest-standing requests for rustdoc, and we get issues about it all the time. People expect to be able to run examples, and so if the example doesn't run, we should tell them in some fashion.

Is there some way we can address both concerns here?

[bluss]

I guess it's just an issue of how to formulate it.

Something more matter of fact would be good like "This example is not tested automatically." Warning triangle can stay?

[est31]

Is there some way we can address both concerns here?

My main problem is the inaccuracy. Whether a test is ignored or not is not the same as whether a test actually compiles and runs. Just look at the example @bluss linked. The test obviously will compile, but its ignored. The reverse can be true as well: if you have changed an API but forgot to run cargo test before uploading, the doc tests might not have been tested.

Its the same issue I have with this crates.io batches thing: I want the info to be accurate, and not just be some indicator. This is Rust, not C!

I'd agree with the feature if rustdoc would actually test each single example for whether it compiles and runs, and display that info instead.

[GuillaumeGomez]

Well, every non-ignored code block is tested and run, so I'm not sure to understand what you're talking about.

[arielb1]

I think as a workaround you could comment the code out, e.g.

//! ```rust,ignore
//! # #[cfg(never)] mod foo {
//! use itertools::Itertools;
//! # }
//! ```

[Rufflewind]

I sometimes write Rust-like pseudocode to explain concepts where normal Rust code would be too verbose or detract from the main topic. The presence of syntax highlighting improves readability.

I find this warning rather discouraging, especially the exclamation mark that is normally used for unsafe code. Besides, there's ways to work around this kind of stuff, so all it does is to force doc writers to find more unsightly hacks like @arielb1's example, or give up syntax highlighting for no good reason.

I think rather than to disparage code blocks that are untested with scary signs, consider adding some positive decoration to the code blocks that are tested, like "this code is tested" with a glowy green border or something, perhaps with some buttons for copy-pasting the original code and/or exposing the # lines.

[est31]

perhaps with some buttons for copy-pasting the original code

First, on all operating systems I've tried on you can just select code and copy it by pressing some keys, so its not really needed, second usually example code is not properly licensed. Most times its under the same license as the code around it, so you'd have to copy the entire attribution/license headers as well. So I don't think one should go down that path.

[QuietMisdreavus]

I'm looking at touching this, at least to tweak the phrasing. How do the phrases "This sample is not tested" and "This sample deliberately fails to compile" sound?

I'm also looking for a better icon, but sadly INFORMATION SOURCE is a box on my work computer, so i'd need to find one that is provided by the fonts we bundle with rustdoc.

[est31]

@QuietMisdreavus what about ⓘ ?

[bluss]

The former sounds good. Should it say "example" instead of sample?

[QuietMisdreavus]

@est31 That character works! Thanks!

@bluss "Example" is probably a better word - i'll work that in.

[QuietMisdreavus]

I put these string tweaks in #45815 - feel free to bikeshed over there.

[QuietMisdreavus]

Now #45815 is merged, where does that leave this issue?

[bluss]

Icon and text are improved, I think this is fine to close. Thanks @QuietMisdreavus