Skip to content

regression: rustdoc interprets the * in /** */ doc comments as literal Markdown #92872

Closed
@dalcde

Description

@dalcde
Contributor

Code

I tried this code:

/**
 *     a
 */
pub fn foo() {}

When I run cargo test, I get

running 0 tests

test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s


running 1 test
test src/lib.rs - foo (line 1) ... FAILED

failures:

---- src/lib.rs - foo (line 1) stdout ----
error[E0425]: cannot find value `a` in this scope
 --> src/lib.rs:2:1
  |
3 | a
  | ^ not found in this scope

error: aborting due to previous error

For more information about this error, try `rustc --explain E0425`.
Couldn't compile the test.

failures:
    src/lib.rs - foo (line 1)

test result: FAILED. 0 passed; 1 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.41s

Oddly it doesn't fail with /** replaced by ///.

This worked on rust version 1.60.0-nightly (092e1c9d2 2022-01-09) but failed on rust version 1.60.0-nightly (1409c015b 2022-01-11)

Activity

added
C-bugCategory: This is a bug.
regression-untriagedUntriaged performance or correctness regression.
on Jan 13, 2022
added
I-prioritizeIssue: Indicates that prioritization has been requested for this issue.
on Jan 13, 2022
Alexendoo

Alexendoo commented on Jan 13, 2022

@Alexendoo
Member

bisects to 89b9f7b, likely #92357

added
A-doctestsArea: Documentation tests, run by rustdoc
T-rustdocRelevant to the rustdoc team, which will review and decide on the PR/issue.
and removed
regression-untriagedUntriaged performance or correctness regression.
on Jan 13, 2022
added this to the 1.60.0 milestone on Jan 14, 2022
camelid

camelid commented on Jan 14, 2022

@camelid
Member
camelid

camelid commented on Jan 14, 2022

@camelid
Member

The docs for the MCVE render with an itemized bullet at the top of the page on nightly, but not on stable. I think this is why replacing the /** with /// makes the error go away: the * is interpreted as part of the docs, so it triggers the indented text to be treated as a code block (it seems there must be preceding text to trigger the code block formatting).

image

camelid

camelid commented on Jan 14, 2022

@camelid
Member

It seems like /** */ comments are completely broken:

/**
 * Hello!
 */
pub fn foo() {}

image

I still don't understand how that change could've cause this though; the particular code removed was related to trimming whitespace, not asterisks. Must be a strange cross-interaction.

changed the title [-]Nightly rust mistakes comment for doctest[/-] [+]regression: rustdoc interprets the `*` in `/** */` doc comments as literal Markdown[/+] on Jan 14, 2022
added
A-markdown-parsingArea: Markdown parsing for doc-comments
and removed
A-doctestsArea: Documentation tests, run by rustdoc
on Jan 14, 2022

15 remaining items

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

Metadata

Metadata

Labels

A-markdown-parsingArea: Markdown parsing for doc-commentsC-bugCategory: This is a bug.T-rustdocRelevant to the rustdoc team, which will review and decide on the PR/issue.regression-from-stable-to-nightlyPerformance or correctness regression from stable to nightly.

Type

No type

Projects

No projects

Relationships

None yet

    Development

    Participants

    @dalcde@Alexendoo@GuillaumeGomez@camelid@rustbot

    Issue actions

      regression: rustdoc interprets the `*` in `/** */` doc comments as literal Markdown · Issue #92872 · rust-lang/rust