I have the following commented code in a crate:
/// Complex Expression
///
/// - The `Undefined` variant is used as a placeholder during code
/// transformations. It must never occur in the final result.
pub enum Cexp {
Undefined,
Unimplemented,
}
When running cargo test
on the crate it triggers a doctest run, which fails to compile. (In the playground make sure to run TEST rather than BUILD.)
Doc-tests playground
running 1 test
test src/lib.rs - Cexp (line 3) ... FAILED
failures:
---- src/lib.rs - Cexp (line 3) stdout ----
error: unknown start of token: `
--> src/lib.rs:4:7
|
1 | - The `Undefined` variant is used as a placeholder during code
| ^
The actual error message is of no concern. The rust compiler chokes on the comment text, which is no surprise. But why does this comment trigger a doctest run? According to the documentation doctests are supposed to be fenced with ```
, which is not the case here.
This behavior is actually explained in the documentation. In the very bottom it says (emphasis mine):
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.
...
However, it's preferable to use fenced code blocks over indented code blocks. Not only are fenced code blocks considered more idiomatic for Rust code, but there is no way to use directives such as
ignore
orshould_panic
with indented code blocks.
If you love us? You can donate to us via Paypal or buy me a coffee so we can maintain and grow! Thank you!
Donate Us With