Skip to content

Incorrect span used for doctest when both an outer doc comment (///) and inner doc comment (//!) are used on a module #117753

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
IceTDrinker opened this issue Nov 9, 2023 · 1 comment
Labels
A-diagnostics Area: Messages for errors, warnings, and lints A-doctests Area: Documentation tests, run by rustdoc T-compiler Relevant to the compiler team, which will review and decide on the PR/issue. T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue.

Comments

@IceTDrinker
Copy link

IceTDrinker commented Nov 9, 2023

Code

my_module.rs

//! Malformed example
//!
//! ```
//! not valid rust code
//! ```

lib.rs

/// Some outer doc, remove/comment it to get the output I would expect
pub mod my_module;

cargo +nightly test --doc

Current output

cargo +nightly test --doc
   Compiling doctest_wrong_line v0.1.0 (/doctest_wrong_line)
    Finished test [unoptimized + debuginfo] target(s) in 0.02s
   Doc-tests doctest_wrong_line

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

failures:

---- src/lib.rs - my_module (line 4) stdout ----
error: expected one of `!`, `.`, `::`, `;`, `?`, `{`, `}`, or an operator, found `valid`
 --> src/lib.rs:5:5
  |
3 | not valid rust code
  |     ^^^^^ expected one of 8 possible tokens

error: aborting due to previous error

Couldn't compile the test.

failures:
    src/lib.rs - my_module (line 4)

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

error: doctest failed, to rerun pass `--doc`

Desired output

cargo +nightly test --doc
   Compiling doctest_wrong_line v0.1.0 (/doctest_wrong_line)
    Finished test [unoptimized + debuginfo] target(s) in 0.02s
   Doc-tests doctest_wrong_line

running 1 test
test src/my_module.rs - my_module (line 3) ... FAILED

failures:

---- src/my_module.rs - my_module (line 3) stdout ----
error: expected one of `!`, `.`, `::`, `;`, `?`, `{`, `}`, or an operator, found `valid`
 --> src/my_module.rs:4:5
  |
3 | not valid rust code
  |     ^^^^^ expected one of 8 possible tokens

error: aborting due to previous error

Couldn't compile the test.

failures:
    src/my_module.rs - my_module (line 3)

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

error: doctest failed, to rerun pass `--doc`

Rationale and extra context

the lines indicate lib.rs as the location where the failure happens which is not correct though I understand it may appear so to the compiler given it might be fusing the doc content at some point and not keep sub blocks original span (though it's confusing as I ended up in my lib.rs at a location that did not exist)

Basically adding a /// comment on top of the module on the lib.rs should not be modifying the span of the docstring coming from the module

In my case it indicated a non existent line in a rather small lib.rs

Other cases

No response

Anything else?

I tried various combinations of keywords to find related issues in the repo but could not find any (though some look similar they use an include macro which is not the case here #81070)

Thanks for the high quality of the tooling, those are edge cases which happen because well, if it can happen it will 😄

Cheers

@IceTDrinker IceTDrinker added A-diagnostics Area: Messages for errors, warnings, and lints T-compiler Relevant to the compiler team, which will review and decide on the PR/issue. labels Nov 9, 2023
@rustbot rustbot added the needs-triage This issue may need triage. Remove it if it has been sufficiently triaged. label Nov 9, 2023
@IceTDrinker IceTDrinker changed the title Incorrect span used for doctest when bot an outer doc comment (///) and inner doc comment (//!) are used on a module Incorrect span used for doctest when both an outer doc comment (///) and inner doc comment (//!) are used on a module Nov 9, 2023
@IceTDrinker
Copy link
Author

It seems it can even prevent some docstrings from running, but maybe that's a known choice for doctests with //!

cargo +nightly test --doc -- my_module::
    Finished test [unoptimized + debuginfo] target(s) in 0.02s
   Doc-tests doctest_wrong_line

running 0 tests

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

@saethlin saethlin added T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue. A-doctests Area: Documentation tests, run by rustdoc and removed needs-triage This issue may need triage. Remove it if it has been sufficiently triaged. labels Nov 10, 2023
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
A-diagnostics Area: Messages for errors, warnings, and lints A-doctests Area: Documentation tests, run by rustdoc T-compiler Relevant to the compiler team, which will review and decide on the PR/issue. T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue.
Projects
Status: No status
Development

No branches or pull requests

3 participants