diff --git a/src/doc/rustdoc/src/how-to-write-documentation.md b/src/doc/rustdoc/src/how-to-write-documentation.md
index 1fa9f814476..acab1a93690 100644
--- a/src/doc/rustdoc/src/how-to-write-documentation.md
+++ b/src/doc/rustdoc/src/how-to-write-documentation.md
@@ -254,6 +254,19 @@ characters:
So, no need to manually enter those Unicode characters!
+### Adding a warning block
+
+If you want to make a warning or similar note stand out in the documentation,
+you can wrap it like this:
+
+```md
+/// documentation
+///
+///
A big warning!
+///
+/// more documentation
+```
+
[`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 b1de8c1529e..da4da50106a 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 {
+p, .docblock > .warning {
/* 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,7 @@ p {
}
/* 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 {
+p:last-child, .docblock > .warning:last-child {
margin: 0;
}
@@ -1096,7 +1096,7 @@ pre.rust .doccomment {
}
.example-wrap.ignore .tooltip {
- color: var(--codeblock-ignore-color);
+ color: var(--codeblock-ignore-color);
}
.example-wrap.compile_fail:hover .tooltip,
@@ -1124,6 +1124,26 @@ pre.rust .doccomment {
font-size: 1.25rem;
}
+/* This class only exists 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);
+ 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: "ⓘ";
+ position: absolute;
+ left: -25px;
+ top: 5px;
+ font-weight: bold;
+ font-size: 1.25rem;
+}
+
a.test-arrow {
visibility: hidden;
position: absolute;
diff --git a/src/librustdoc/html/static/css/themes/ayu.css b/src/librustdoc/html/static/css/themes/ayu.css
index d8dae51eb1b..c81a80eeca0 100644
--- a/src/librustdoc/html/static/css/themes/ayu.css
+++ b/src/librustdoc/html/static/css/themes/ayu.css
@@ -31,6 +31,7 @@ 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);
--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 2b302988734..0f8b1dc24a6 100644
--- a/src/librustdoc/html/static/css/themes/dark.css
+++ b/src/librustdoc/html/static/css/themes/dark.css
@@ -26,6 +26,7 @@
--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);
--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 56fd8cbef12..39ea44a1165 100644
--- a/src/librustdoc/html/static/css/themes/light.css
+++ b/src/librustdoc/html/static/css/themes/light.css
@@ -26,6 +26,7 @@
--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);
--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 49484ee0869..38180aef762 100644
--- a/tests/rustdoc-gui/src/test_docs/lib.rs
+++ b/tests/rustdoc-gui/src/test_docs/lib.rs
@@ -65,6 +65,18 @@ impl Foo {
pub fn must_use(&self) -> bool {
true
}
+
+ /// hello
+ ///
+ /// this is a warning
+ ///
+ /// done
+ pub fn warning1() {}
+
+ /// Checking there is no bottom margin if "warning" is the last element.
+ ///
+ /// this is a warning
+ pub fn warning2() {}
}
impl AsRef for Foo {
diff --git a/tests/rustdoc-gui/warning-block.goml b/tests/rustdoc-gui/warning-block.goml
new file mode 100644
index 00000000000..2a935bd1a9b
--- /dev/null
+++ b/tests/rustdoc-gui/warning-block.goml
@@ -0,0 +1,45 @@
+// Test to check that the "warning blocks" are displayed as expected.
+go-to: "file://" + |DOC_PATH| + "/test_docs/struct.Foo.html"
+show-text: true
+
+define-function: (
+ "check-warning",
+ (theme, color, border_color, background_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-warning-1", {
+ "margin-bottom": "12px",
+ "color": |color|,
+ "border-left": "2px solid " + |border_color|,
+ "background-color": |background_color|,
+ })
+ assert-css: ("#doc-warning-2", {
+ "margin-bottom": "0px",
+ "color": |color|,
+ "border-left": "2px solid " + |border_color|,
+ "background-color": |background_color|,
+ })
+ },
+)
+
+call-function: ("check-warning", {
+ "theme": "ayu",
+ "color": "rgb(197, 197, 197)",
+ "border_color": "rgb(255, 142, 0)",
+ "background_color": "rgba(0, 0, 0, 0)",
+})
+call-function: ("check-warning", {
+ "theme": "dark",
+ "color": "rgb(221, 221, 221)",
+ "border_color": "rgb(255, 142, 0)",
+ "background_color": "rgba(0, 0, 0, 0)",
+})
+call-function: ("check-warning", {
+ "theme": "light",
+ "color": "rgb(0, 0, 0)",
+ "border_color": "rgb(255, 142, 0)",
+ "background_color": "rgba(0, 0, 0, 0)",
+})