rustdoc: extend warning block for admonitions

In AsciiDoc and GitHub's Markdown, admonitions (a.k.a. callouts or alerts) consist of five types (NOTE, TIP, IMPORTANT, CAUTION, and WARNING).^1 reStructuredText has even more types.^3

However, rustdoc consist only of a warning block.^4 So, at this point, this can be used for purposes other than just warnings. For example, looking at usage examples in the clap crate, I think it's also used for purposes like NOTE or TIP.^5

/// <div class="warning">
///
/// **NOTE:** This choice is propagated to all child subcommands.
///
/// </div>
///
/// <div class="warning">
///
/// **NOTE:** Default behaviour is [`ColorChoice::Auto`].
///
/// </div>

I think warning is correct for the first <div>, but note or tip would be more appropriate for the second one. Since Command::color propagates to all child subcommands, overlooking it can cause unintended colors to appear or disappear. Therefore, I think the warning class is appropriate. However, the fact that the default behaviour is ColorChoice::Auto is merely supplementary information. Since this does not lead to any dangerous errors or unintended behavior, I think the warning class is inappropriate.

If representing the above in GitHub's Markdown, I think the second is more appropriate than the first:

---

[!WARNING]
This choice is propagated to all child subcommands.

[!WARNING]
Default behaviour is ColorChoice::Auto.

---

[!WARNING]
This choice is propagated to all child subcommands.

[!NOTE]
Default behaviour is ColorChoice::Auto.

---

If the sole purpose is emphasis, I think just the warning class is sufficient. However, from a semantic standpoint, I don't think it is correct to represent everything using the warning class.

Therefore, I propose adding the note, tip, important, and caution classes to rustdoc.

+/// <div class="note">...</div>
+/// <div class="tip">...</div>
+/// <div class="important">...</div>
+/// <div class="caution">...</div>
/// <div class="warning">...</div>

It seems that these five types are supported by many markup languages, so I proposed them. However, regarding rustdoc, if other types are more appropriate, I think it would be desirable to remove the types I proposed, or add types I didn't propose.

• https://users.rust-lang.org/t/why-do-admonitions-for-rustdoc-consist-only-of-a-warning-block/142455
• #79710

@rustbot label +A-markdown-parsing +C-feature-request +T-rustdoc