Description
I tried this code:
/*!
* ```
* let thing = "**/*.css";
* ```
*/
/// ```
/// let thing = "**/*.css";
/// ```
pub fn get_thing() -> &'static str {
let thing = "**/*.css";
thing
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn it_works() {
let result = get_thing();
assert_eq!(result, "**/*.css");
}
}
I expected to see this happen: The docs to compile.
Instead, this happened:
The docs fail to compile with this message:
error: prefix
css
is unknown
--> src/lib.rs:3:22
|
3 | * let thing = "/*.css";
| ^^^ unknown prefix
|
= note: prefixed identifiers and literals are reserved since Rust 2021
help: consider inserting whitespace here
|
3 | * let thing = "/*.css ";
| +error: prefix
css
is unknown
--> src/lib.rs:11:23
|
11 | let thing = "/*.css";
| ^^^ unknown prefix
|
= note: prefixed identifiers and literals are reserved since Rust 2021
help: consider inserting whitespace here
|
11 | let thing = "/*.css ";
| +error[E0758]: unterminated block comment
--> src/lib.rs:23:31
|
23 | assert_eq!(result, "**/*.css");
| _______________________________^
24 | | }
25 | | }
| |__^For more information about this error, try
rustc --explain E0758
.
error: could not documentrustdoc_issue
Meta
rustc --version --verbose
:
rustc 1.80.0 (051478957 2024-07-21)
binary: rustc
commit-hash: 051478957371ee0084a7c0913941d2a8c4757bb9
commit-date: 2024-07-21
host: x86_64-unknown-linux-gnu
release: 1.80.0
LLVM version: 18.1.7
I've also reproduced on nightly.
Activity
GKFX commentedon Aug 28, 2024
In your example, the
*/
on line three, inside the string, terminates the doc comment. This is something that can be depended on in working code (example), so changing it would be a breaking change. The next few characters are invalid Rust so the syntax error is expected behaviour.Your second comment can be used OK as is - example.
The reference (https://doc.rust-lang.org/reference/comments.html) makes no mention of markdown syntax when defining comments, so I would not expect presence of a string within backticks to make any difference to parsing.
@rustbot label -C-bug
nathanosdev commentedon Aug 29, 2024
That's fair, so then would it be possible to add a way to escape the characters in a way that does not affect the final output?
I can use
\*\*\/\*
instead of**/*
but then it's still present in the output.GKFX commentedon Sep 7, 2024
This can technically be done as below, although it does look rather odd. Considering that the convention is to use
///
doc comments, and those don't have an issue with nested comment characters, I think a special syntax just for/** */
doc comments is unlikely to happen. I don't believe Markdown offers a way around this.nathanosdev commentedon Sep 10, 2024
I see. Okay well for now I've switched to
///
doc comments anyway. Thanks for the update to the docs too 👍