From 9fcc61bf9f2148ede0e97537f4b1ecc80e675f09 Mon Sep 17 00:00:00 2001 From: Benjamin Sago Date: Tue, 29 May 2018 11:31:14 +0200 Subject: [PATCH 1/2] 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 fd7d1713ca574..61cfebb97e74c 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. From 8f8a7b9a7b236ba02afc1589901acc6b125d6fec Mon Sep 17 00:00:00 2001 From: Benjamin Sago Date: Tue, 29 May 2018 16:04:37 +0200 Subject: [PATCH 2/2] Phrasing tweak in doctest docs --- src/doc/rustdoc/src/documentation-tests.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/doc/rustdoc/src/documentation-tests.md b/src/doc/rustdoc/src/documentation-tests.md index 61cfebb97e74c..3253e4d6269d4 100644 --- a/src/doc/rustdoc/src/documentation-tests.md +++ b/src/doc/rustdoc/src/documentation-tests.md @@ -305,6 +305,6 @@ These, too, are documented in the CommonMark specification, in the 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, +Not only are fenced code blocks considered more idiomatic for Rust code, but there is no way to use directives such as `ignore` or `should_panic` with indented code blocks.