Add warning sections in rustdoc

[GuillaumeGomez]

Fixes #73935.

It looks like this:

I used the same style than code blocks in case. :)

r? @jyn514

[rust-highfive]

Some changes occurred in HTML/CSS/JS.

cc @GuillaumeGomez

A change occurred in the Ayu theme.

cc @Cldfire

Some changes occurred in HTML/CSS themes.

cc @GuillaumeGomez

[jyn514]

I think it also makes sense to add info sections (like in https://docs.rs/tracing/0.1.22/tracing/span/struct.Span.html#method.record), but that can maybe wait for a follow-up.

[jyn514]

I would prefer to put this in the 'advanced features' section - I don't expect many people to use it, and having a whole chapter for the one feature seems like overkill, I think people will expect 'how do I write rust documentation' which is not what this is.

[GuillaumeGomez]

We have already a lot of things in there, making access to information more complicated. I expect for us to have more "front-end" tweaks like that so I think it's better to have it in a section on its own.

[jyn514]

Hmm, if you plan to have more tweaks, does it make sense to plan them out ahead of time? I don't want to land these piece-meal and realize we ended with a bunch of similar ones that don't address people's needs.

[GuillaumeGomez]

I think it also makes sense to add info sections (like in https://docs.rs/tracing/0.1.22/tracing/span/struct.Span.html#method.record), but that can maybe wait for a follow-up.

Good idea, however I'd prefer put it into another PR so that we can have small and focused ones.

[Nemo157]

section seems wrong for this:

Do not use the <section> element as a generic container; this is what <div> is for, especially when the sectioning is only for styling purposes. A rule of thumb is that a section should logically appear in the outline of a document.
— https://developer.mozilla.org/en-US/docs/Web/HTML/Element/section

I also wonder about namespacing the class somehow, to avoid issues with doc pages embedded within other contexts (like docs.rs, which has its own div.warning css).

[GuillaumeGomez]

@Nemo157 It's both very good points. Rustdoc embed its content inside a main element so I'll use this rule too to enforce it to avoid conflicts.

[GuillaumeGomez]

Fixed issues!

[GuillaumeGomez]

@rfcbot fcp merge

This feature allows to have an official way in rustdoc to add small text warning blocks. We saw with the @rust-lang/docs-rs team about the class name to prevent potential conflicts with docs.rs style.

[rfcbot]

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

• @GuillaumeGomez
• @Manishearth
• @jyn514
• @ollie27

Concerns:

• what syntax should be used? (Add warning sections in rustdoc #79677 (comment))

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.

[jyn514]

I think it would be great to hear from some authors in the community whether they'd use this or not. Maybe @dtolnay, @Darksonn, @BurntSushi would be interested in giving feedback? The goal is to allow making Notes like https://docs.rs/tracing/0.1.22/tracing/span/struct.Span.html#method.record easy to add and consistent across documentation for different projects.

[jyn514]

Hmm, if you plan to have more tweaks, does it make sense to plan them out ahead of time? I don't want to land these piece-meal and realize we ended with a bunch of similar ones that don't address people's needs.

[GuillaumeGomez]

Hmm, if you plan to have more tweaks, does it make sense to plan them out ahead of time? I don't want to land these piece-meal and realize we ended with a bunch of similar ones that don't address people's needs.

@jyn514 I expect the class:class to be documented there as well as the "information block". And I think there will be more in the future. Again, I think it's better to not put too much into the "advanced features" chapter, specially in this case considering that a few other "front-end changes" are coming all at once. :)

[Darksonn]

I certainly think this seems useful. I would probably use it rather infrequently, but footguns like block_in_place deserve warnings that stand out. We already use a similar feature in the tutorial on our website.

I could also imagine wanting a blue info box for larger pieces of documentation such as the select! macro.

[dtolnay]

Exposing this by HTML tags <div class="rustdoc-warning">...</div> in the source file is not appealing to me. I think Phabricator does this better, see https://secure.phabricator.com/book/phabricator/article/remarkup/ where it covers NOTE:, WARNING:, IMPORTANT:.

Basically it would render this as a warning:

/// WARNING: it doesn't work yet.

and remains suitably readable in the source file.

[GuillaumeGomez]

I could also imagine wanting a blue info box for larger pieces of documentation such as the select! macro.

Already scheduled! :D

@dtolnay But then it's not markdown compliant anymore and becomes a rustdoc extension. And I don't really like your suggestion as is. If we go in this direction, why not something like:

/// /!\ this is the warning text /!\

?

[jyn514]

@dtolnay how would that syntax work for multi-line blocks? Are you expecting these to all render as the same warning?

/// WARNING: first line
/// second line, still a warning
///
/// after a line break, no longer part of the `rustdoc-warning` block

[Darksonn]

For comparison, this is what the markdown parser we happen to use on the Tokio website accepts:

[[info]]
| Many of Tokio's types are named the same as their synchronous equivalent in
| the Rust standard library. When it makes sense, Tokio exposes the same APIs
| as `std` but using `async fn`.

I don't exactly love this syntax, but I find it somewhat better than the html tag.

[GuillaumeGomez]

So, adding an extension to rust doc comment syntax to generate a warning block seems like another feature. I'm not really convinced with the suggestions, and in the end, we still need to generate the HTML we have here. :)

[jyn514]

@GuillaumeGomez well, the syntax is important to know before stabilizing. If you want to make this available on nightly only I'm ok with that, but making this insta-stable means the HTML syntax can't be removed, and people have already raised concerns that it could be improved.

[jyn514]

@rfcbot concern what syntax should be used?

[GuillaumeGomez]

For me it's another debate. In the end, we still want to generate his HTML which needs to be present before we even add the syntax extension. I think it's two different issues.

[GuillaumeGomez]

@rfcbot rfc cancel

[GuillaumeGomez]

I opened #79710 to have the debate over the syntax extension somewhere else. We discussed about it with @jyn514 for quite some time and decided to not document the current behavior and to only document the syntax extension once approved to not enforce the usage of HTML directly.

[camelid]

@rfcbot rfc cancel

I don't think this worked. Instead you need @rfcbot cancel.

[jyn514]

FWIW I am against even putting this on nightly until we decide on a syntax, it means we'll be giving precedence to that syntax over the others and there will be pressure to stabilize that syntax because it exists and people are using it. This is especially bad for rustdoc because docs.rs uses nightly by default.

[camelid]

Canceling FCP since it's already de facto cancelled:

@rfcbot cancel

[rfcbot]

@camelid proposal cancelled.

[bors]

☔ The latest upstream changes (presumably #85156) made this pull request unmergeable. Please resolve the merge conflicts.

[camelid]

I'm going to close this for now in favor of #79710. Once we decide on a path forward, this can be re-opened or a new PR can be created.