Skip to content

Multiline module level docs cannot handle /* in a string #129685

Closed
rust-lang/reference
#1602
@nathanosdev

Description

@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.

Activity

added
needs-triageThis issue may need triage. Remove it if it has been sufficiently triaged.
on Aug 28, 2024
GKFX

GKFX commented on Aug 28, 2024

@GKFX
Contributor

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

nathanosdev commented on Aug 29, 2024

@nathanosdev
Author

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.

added
T-rustdocRelevant to the rustdoc team, which will review and decide on the PR/issue.
A-parserArea: The lexing & parsing of Rust source code to an AST
C-discussionCategory: Discussion or questions that doesn't represent real issues.
and removed
needs-triageThis issue may need triage. Remove it if it has been sufficiently triaged.
on Sep 1, 2024
GKFX

GKFX commented on Sep 7, 2024

@GKFX
Contributor

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

nathanosdev commented on Sep 10, 2024

@nathanosdev
Author

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    A-parserArea: The lexing & parsing of Rust source code to an ASTC-discussionCategory: Discussion or questions that doesn't represent real issues.T-rustdocRelevant to the rustdoc team, which will review and decide on the PR/issue.

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

      Development

      Participants

      @GKFX@saethlin@nathanosdev@rustbot

      Issue actions

        Multiline module level docs cannot handle `/*` in a string · Issue #129685 · rust-lang/rust