rustdoc: Test & document test_harness code block attribute
#148183
Conversation
rustbot
added
S-waiting-on-review
|
rustbot has assigned @GuillaumeGomez. Use |
| None, | ||
| Some(Vec<String>), | ||
| } | ||
|
|
There was a problem hiding this comment.
It's not any old ENBF1 (variant), it's ABNF2 specifically (from IETF RFC 5234) which I previously didn't know about (and thus was confused about the syntax).
Footnotes
| /// delimited-attribute-list = OPEN-CURLY-BRACKET attribute-list CLOSE-CURLY-BRACKET | ||
| /// token-list = [sep] token *(sep token) [sep] | ||
| /// comment = OPEN_PAREN *(all characters) CLOSE_PAREN | ||
| /// comment = OPEN_PAREN *<all characters except closing parentheses> CLOSE_PAREN |
There was a problem hiding this comment.
Prose terminals are to be denoted by <…> not by (…) (which is grouping) per IETF RFC 5234 (Ctrl+F for prose-val).
fmease
force-pushed
the
rustdoc-test-n-doc-doctest-test-harness
branch
from
eab1d61 to
5e7f083
Compare
This comment has been minimized.
This comment has been minimized.
fmease
force-pushed
the
rustdoc-test-n-doc-doctest-test-harness
branch
from
5e7f083 to
c687f89
Compare
This comment has been minimized.
This comment has been minimized.
fmease
force-pushed
the
rustdoc-test-n-doc-doctest-test-harness
branch
from
c687f89 to
f71d897
Compare
This comment has been minimized.
This comment has been minimized.
fmease
force-pushed
the
rustdoc-test-n-doc-doctest-test-harness
branch
from
f71d897 to
9a78729
Compare
This comment has been minimized.
This comment has been minimized.
fmease
force-pushed
the
rustdoc-test-n-doc-doctest-test-harness
branch
from
9a78729 to
3a17eba
Compare
| Code blocks can be annotated with attributes that help `rustdoc` do the right | ||
| thing when testing your code: | ||
| Code blocks can be annotated with attributes that tell `rustdoc` how to build and interpret the test. | ||
| They follow the triple backtick in the opening line. |
There was a problem hiding this comment.
Not necessarily triple, it can be ten if you want. ^^'
There was a problem hiding this comment.
So I'd say (or something along the lines):
| They follow the triple backtick in the opening line. | |
| They follow the backticks marking the beginning of the code block. |
There was a problem hiding this comment.
Yea it can also be ~~~ ^^'. I've used triple backtick because that's what's also used at the top of the file. We do link to the CommonMark spec later for the full rules.
But yeah, I should probably rephrase that.
There was a problem hiding this comment.
I keep forgetting about ~~~... Markdown is too flexible 😅
| They follow the triple backtick in the opening line. | ||
| As such, they share the place with language strings like `rust` or `text`. | ||
| Multiple attributes can be provided by separating them with commas, spaces or tabs. | ||
| You can also write comments which are enclosed in parentheses `(…)`. |
There was a problem hiding this comment.
Maybe link to the relevant part of the book which explains the syntax of codeblock attributes instead?
| a Rust code block whereas the two others add a "rust" CSS class on the code block. | ||
| To be noted, `rust` and `{.rust}` / `{class=rust}` have different effects: | ||
| `rust` indicates that this is a Rust code block whereas | ||
| the two others add a "rust" CSS class on the code block. |
There was a problem hiding this comment.
I think this precision is important as HTML is not the only output we have:
| the two others add a "rust" CSS class on the code block. | |
| the two others add a "rust" CSS class on the code block in the generated HTML. |
4 participants
They were fully untested and undocumented previously despite being stable.
Context: #t-rustdoc > `test_harness` langstr @ 💬.
While at it, I've also improved the documentation for code block attributes in general.
I was only inspired to do so because there was no good place for
test_harnessand because it got hard to skim due to a lack of subsubsections.