Multiline module level docs cannot handle /* in a string

[nathanosdev]

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 document rustdoc_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.

[GKFX]

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]

I would not expect presence of a string within backticks to make any difference to parsing

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]

would it be possible to add a way to escape the characters in a way that does not affect the final output

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.

/*!
 * ```
 * # // /*
 * let thing = "**/*.css";
 * ```
 */

[nathanosdev]

I see. Okay well for now I've switched to /// doc comments anyway. Thanks for the update to the docs too 👍