From 9fcc61bf9f2148ede0e97537f4b1ecc80e675f09 Mon Sep 17 00:00:00 2001 From: Benjamin Sago Date: Tue, 29 May 2018 11:31:14 +0200 Subject: [PATCH] Mention spec and indented blocks in doctest docs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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! --- src/doc/rustdoc/src/documentation-tests.md | 24 ++++++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/src/doc/rustdoc/src/documentation-tests.md b/src/doc/rustdoc/src/documentation-tests.md index fd7d1713ca5..61cfebb97e7 100644 --- a/src/doc/rustdoc/src/documentation-tests.md +++ b/src/doc/rustdoc/src/documentation-tests.md @@ -284,3 +284,27 @@ environment that has no network access. compiles, then the test will fail. However please note that code failing with the current Rust release may work in a future release, as new features are added. + +## Syntax reference + +The *exact* syntax for code blocks, including the edge cases, can be found +in the [Fenced Code Blocks](https://spec.commonmark.org/0.28/#fenced-code-blocks) +section of the CommonMark specification. + +Rustdoc also accepts *indented* code blocks as an alternative to fenced +code blocks: instead of surrounding your code with three backticks, you +can indent each line by four or more spaces. + +``````markdown + let foo = "foo"; + assert_eq!(foo, "foo"); +`````` + +These, too, are documented in the CommonMark specification, in the +[Indented Code Blocks](https://spec.commonmark.org/0.28/#indented-code-blocks) +section. + +However, it's preferable to use fenced code blocks over indented code blocks. +Not only are fenced code blocks the more popular choice in the Rust community, +but there is no way to use directives such as `ignore` or `should_panic` with +indented code blocks.