rust-lang / rust-lang/rust

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

Open
#117,753 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

A-diagnostics A-doctests T-compiler T-rustdoc
Dominant language
Rust
Stars
119k
Forks
16.1k
PR merge metrics
PR metrics pending

Description

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 https://github.com/rust-lang/rust/issues/81070)

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

Cheers

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by reproducing the issue with the shown my_module.rs and lib.rs files using cargo +nightly test --doc. Compare the current and desired source paths and line numbers when both //! and /// comments are present. Done means the doctest failure points to src/my_module.rs and its correct line rather than the outer module declaration in lib.rs.

Written by the indexing model from the issue text.

Assessment

Tech stack
rust
Domain
compilers, testing-qa
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
38/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.