diff --git a/src/doc/rustdoc/src/how-to-write-documentation.md b/src/doc/rustdoc/src/how-to-write-documentation.md
index acab1a93690c5..7d22e70fecd80 100644
--- a/src/doc/rustdoc/src/how-to-write-documentation.md
+++ b/src/doc/rustdoc/src/how-to-write-documentation.md
@@ -254,7 +254,7 @@ characters:
So, no need to manually enter those Unicode characters!
-### Adding a warning block
+### Adding a note/warning/danger block
If you want to make a warning or similar note stand out in the documentation,
you can wrap it like this:
@@ -267,6 +267,11 @@ you can wrap it like this:
/// more documentation
```
+There are three levels available:
+ * note
+ * warning
+ * danger
+
[`backtrace`]: https://docs.rs/backtrace/0.3.50/backtrace/
[commonmark markdown specification]: https://commonmark.org/
[commonmark quick reference]: https://commonmark.org/help/
diff --git a/src/librustdoc/html/static/css/rustdoc.css b/src/librustdoc/html/static/css/rustdoc.css
index da4da50106abb..c887ff9074980 100644
--- a/src/librustdoc/html/static/css/rustdoc.css
+++ b/src/librustdoc/html/static/css/rustdoc.css
@@ -270,7 +270,7 @@ ul ul, ol ul, ul ol, ol ol {
margin-bottom: .625em;
}
-p, .docblock > .warning {
+p, .docblock > .note, .docblock > .warning, .docblock > .danger {
/* Paragraph spacing at least 1.5 times line spacing per Web Content Accessibility Guidelines.
Line-height is 1.5rem, so line spacing is .5rem; .75em is 1.5 times that.
https://www.w3.org/WAI/WCAG21/Understanding/visual-presentation.html */
@@ -278,7 +278,10 @@ p, .docblock > .warning {
}
/* For the last child of a div, the margin will be taken care of
by the margin-top of the next item. */
-p:last-child, .docblock > .warning:last-child {
+p:last-child,
+.docblock > .note:last-child,
+.docblock > .warning:last-child,
+.docblock > .danger:last-child {
margin: 0;
}
@@ -1124,18 +1127,20 @@ pre.rust .doccomment {
font-size: 1.25rem;
}
-/* This class only exists for users who want to draw attention to a particular element in their
+/* These classes only exist for users who want to draw attention to a particular element in their
documentation. */
-.content .docblock .warning {
- border-left: 2px solid var(--warning-border-color);
+.content .docblock .note,
+.content .docblock .warning,
+.content .docblock .danger {
padding: 14px;
position: relative;
/* The "!important" part is required because the rule is otherwise overruled in this CSS
selector: ".docblock > :not(.more-examples-toggle):not(.example-wrap)" */
overflow-x: visible !important;
}
-.content .docblock .warning::before {
- color: var(--warning-border-color);
+.content .docblock .note::before,
+.content .docblock .warning::before,
+.content .docblock .danger::before {
content: "ⓘ";
position: absolute;
left: -25px;
@@ -1143,6 +1148,24 @@ documentation. */
font-weight: bold;
font-size: 1.25rem;
}
+.content .docblock .note {
+ border-left: 2px solid var(--note-border-color);
+}
+.content .docblock .warning {
+ border-left: 2px solid var(--warning-border-color);
+}
+.content .docblock .danger {
+ border-left: 2px solid var(--danger-border-color);
+}
+.content .docblock .note::before {
+ color: var(--note-border-color);
+}
+.content .docblock .warning::before {
+ color: var(--warning-border-color);
+}
+.content .docblock .danger::before {
+ color: var(--danger-border-color);
+}
a.test-arrow {
visibility: hidden;
diff --git a/src/librustdoc/html/static/css/themes/ayu.css b/src/librustdoc/html/static/css/themes/ayu.css
index c81a80eeca059..0c0ad0e8e5180 100644
--- a/src/librustdoc/html/static/css/themes/ayu.css
+++ b/src/librustdoc/html/static/css/themes/ayu.css
@@ -31,7 +31,9 @@ Original by Dempfi (https://github.com/dempfi/ayu)
--codeblock-error-color: rgba(255, 0, 0, .5);
--codeblock-ignore-hover-color: rgb(255, 142, 0);
--codeblock-ignore-color: rgba(255, 142, 0, .6);
- --warning-border-color: rgb(255, 142, 0);
+ --note-border-color: #00abff;
+ --warning-border-color: #ff8e00;
+ --danger-border-color: #ff2323;
--type-link-color: #ffa0a5;
--trait-link-color: #39afd7;
--assoc-item-link-color: #39afd7;
diff --git a/src/librustdoc/html/static/css/themes/dark.css b/src/librustdoc/html/static/css/themes/dark.css
index 0f8b1dc24a651..d9faed6f83077 100644
--- a/src/librustdoc/html/static/css/themes/dark.css
+++ b/src/librustdoc/html/static/css/themes/dark.css
@@ -26,7 +26,9 @@
--codeblock-error-color: rgba(255, 0, 0, .5);
--codeblock-ignore-hover-color: rgb(255, 142, 0);
--codeblock-ignore-color: rgba(255, 142, 0, .6);
- --warning-border-color: rgb(255, 142, 0);
+ --note-border-color: #0087ff;
+ --warning-border-color: #ff8e00;
+ --danger-border-color: #d22525;
--type-link-color: #2dbfb8;
--trait-link-color: #b78cf2;
--assoc-item-link-color: #d2991d;
diff --git a/src/librustdoc/html/static/css/themes/light.css b/src/librustdoc/html/static/css/themes/light.css
index 39ea44a116544..2eca3a05b692d 100644
--- a/src/librustdoc/html/static/css/themes/light.css
+++ b/src/librustdoc/html/static/css/themes/light.css
@@ -26,7 +26,9 @@
--codeblock-error-color: rgba(255, 0, 0, .5);
--codeblock-ignore-hover-color: rgb(255, 142, 0);
--codeblock-ignore-color: rgba(255, 142, 0, .6);
- --warning-border-color: rgb(255, 142, 0);
+ --note-border-color: #0087ff;
+ --warning-border-color: #ff8e00;
+ --danger-border-color: #d22525;
--type-link-color: #ad378a;
--trait-link-color: #6e4fc9;
--assoc-item-link-color: #3873ad;
diff --git a/tests/rustdoc-gui/src/test_docs/lib.rs b/tests/rustdoc-gui/src/test_docs/lib.rs
index 38180aef762b4..e869049db8556 100644
--- a/tests/rustdoc-gui/src/test_docs/lib.rs
+++ b/tests/rustdoc-gui/src/test_docs/lib.rs
@@ -68,8 +68,12 @@ impl Foo {
/// hello
///
+ /// this is a note
+ ///
/// this is a warning
///
+ /// this is a danger
+ ///
/// done
pub fn warning1() {}
diff --git a/tests/rustdoc-gui/warning-block.goml b/tests/rustdoc-gui/warning-block.goml
index 2a935bd1a9bb5..4af62b334a05e 100644
--- a/tests/rustdoc-gui/warning-block.goml
+++ b/tests/rustdoc-gui/warning-block.goml
@@ -4,42 +4,57 @@ show-text: true
define-function: (
"check-warning",
- (theme, color, border_color, background_color),
+ (theme, color, note_color, warning_color, danger_color),
block {
set-local-storage: {"rustdoc-theme": |theme|, "rustdoc-use-system-theme": "false"}
reload:
// The IDs are added directly into the DOM to make writing this test easier.
+ assert-css: ("#doc-note", {
+ "margin-bottom": "12px",
+ "color": |color|,
+ "border-left": "2px solid " + |note_color|,
+ "background-color": "transparent",
+ })
assert-css: ("#doc-warning-1", {
"margin-bottom": "12px",
"color": |color|,
- "border-left": "2px solid " + |border_color|,
- "background-color": |background_color|,
+ "border-left": "2px solid " + |warning_color|,
+ "background-color": "transparent",
+ })
+ assert-css: ("#doc-danger", {
+ "margin-bottom": "12px",
+ "color": |color|,
+ "border-left": "2px solid " + |danger_color|,
+ "background-color": "transparent",
})
assert-css: ("#doc-warning-2", {
"margin-bottom": "0px",
"color": |color|,
- "border-left": "2px solid " + |border_color|,
- "background-color": |background_color|,
+ "border-left": "2px solid " + |warning_color|,
+ "background-color": "transparent",
})
},
)
call-function: ("check-warning", {
"theme": "ayu",
- "color": "rgb(197, 197, 197)",
- "border_color": "rgb(255, 142, 0)",
- "background_color": "rgba(0, 0, 0, 0)",
+ "color": "#c5c5c5",
+ "note_color": "#00abff",
+ "warning_color": "#ff8e00",
+ "danger_color": "#ff2323",
})
call-function: ("check-warning", {
"theme": "dark",
- "color": "rgb(221, 221, 221)",
- "border_color": "rgb(255, 142, 0)",
- "background_color": "rgba(0, 0, 0, 0)",
+ "color": "#ddd",
+ "note_color": "#0087ff",
+ "warning_color": "#ff8e00",
+ "danger_color": "#d22525",
})
call-function: ("check-warning", {
"theme": "light",
- "color": "rgb(0, 0, 0)",
- "border_color": "rgb(255, 142, 0)",
- "background_color": "rgba(0, 0, 0, 0)",
+ "color": "black",
+ "note_color": "#0087ff",
+ "warning_color": "#ff8e00",
+ "danger_color": "#d22525",
})