Skip to content

Commit 8c806c3

Browse files
committed
Rollup merge of rust-lang#51158 - ogham:patch-1, r=steveklabnik
Mention spec and indented blocks in doctest docs Fixes rust-lang#49717. This commit adds a new section to the Documentation Test docs, which briefly mentions indented code blocks, and links to the CommonMark specification for both. I’m not sure about saying "fenced code blocks the more popular choice in the Rust community” because it seems like I’m speaking for everyone, but I can’t think of a better way to phrase it!
2 parents ad4afd2 + 8f8a7b9 commit 8c806c3

File tree

1 file changed

+24
-0
lines changed

1 file changed

+24
-0
lines changed

src/doc/rustdoc/src/documentation-tests.md

+24
Original file line numberDiff line numberDiff line change
@@ -284,3 +284,27 @@ environment that has no network access.
284284
compiles, then the test will fail. However please note that code failing
285285
with the current Rust release may work in a future release, as new features
286286
are added.
287+
288+
## Syntax reference
289+
290+
The *exact* syntax for code blocks, including the edge cases, can be found
291+
in the [Fenced Code Blocks](https://spec.commonmark.org/0.28/#fenced-code-blocks)
292+
section of the CommonMark specification.
293+
294+
Rustdoc also accepts *indented* code blocks as an alternative to fenced
295+
code blocks: instead of surrounding your code with three backticks, you
296+
can indent each line by four or more spaces.
297+
298+
``````markdown
299+
let foo = "foo";
300+
assert_eq!(foo, "foo");
301+
``````
302+
303+
These, too, are documented in the CommonMark specification, in the
304+
[Indented Code Blocks](https://spec.commonmark.org/0.28/#indented-code-blocks)
305+
section.
306+
307+
However, it's preferable to use fenced code blocks over indented code blocks.
308+
Not only are fenced code blocks considered more idiomatic for Rust code,
309+
but there is no way to use directives such as `ignore` or `should_panic` with
310+
indented code blocks.

0 commit comments

Comments
 (0)