Doc-test reports “expected item, found keyword let” when the actual problem is a missing semicolon elsewhere

[skr2005]

To reproduce

/// # Example
///
/// ```
/// use test_lib::add;
///
/// let p = add(3, 2);
///
/// assert_eq!(p, 5);
/// // missing a semicolon next line
/// assert_eq!(add(2, 2), 4)
/// assert_eq!(add(5, 0), 5);
/// ```
pub fn add(left: u64, right: u64) -> u64 {
    left + right
}

1. Put the above code in src/lib.rs of a new cargo project named test_lib.

2. Run:

   cargo test --doc

Actual output

   Doc-tests test_lib

running 1 test
test src\lib.rs - add (line 3) ... FAILED

failures:

---- src\lib.rs - add (line 3) stdout ----
error: expected item, found keyword `let`
 --> src\lib.rs:6:1
  |
3 | let p = add(3, 2);
  | ^^^
  | `let` cannot be used for global variables
  | help: consider using `static` or `const` instead of `let`
  |
  = note: for a full list of items that can appear in modules, see https://doc.rust-lang.org/reference/items.html

error: aborting due to 1 previous error

Couldn't compile the test.

Expected output

I would expect the error message to be around the actual problematic line, or with an additional hint saying the error is possibly due to a missing semicolon somewhere.

Meta

rustc --version --verbose:

binary: rustc
commit-hash: 17067e9ac6d7ecb70e50f92c1944e545188d2359
commit-date: 2025-05-09
host: x86_64-pc-windows-gnu
release: 1.87.0
LLVM version: 20.1.1

rustdoc --version --verbose:

rustdoc 1.87.0 (17067e9ac 2025-05-09)
binary: rustdoc
commit-hash: 17067e9ac6d7ecb70e50f92c1944e545188d2359
commit-date: 2025-05-09
host: x86_64-pc-windows-gnu
release: 1.87.0
LLVM version: 20.1.1

Also reproducible on nightly.

rustc --version --verbose:

rustc 1.89.0-nightly (573a01569 2025-06-12)
binary: rustc
commit-hash: 573a01569000d395498a5f98f916d6e5305ac81a
commit-date: 2025-06-12
host: x86_64-pc-windows-gnu
release: 1.89.0-nightly
LLVM version: 20.1.5

rustdoc --version --verbose:

rustdoc 1.89.0-nightly (573a01569 2025-06-12)
binary: rustdoc
commit-hash: 573a01569000d395498a5f98f916d6e5305ac81a
commit-date: 2025-06-12
host: x86_64-pc-windows-gnu
release: 1.89.0-nightly
LLVM version: 20.1.5

[smanilov]

Thanks for opening this issue.

To help devs track down the cause: note that the issue does not appear if the test is not a doctest:

pub fn add(left: u64, right: u64) -> u64 {
    left + right
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn it_works() {
        let p = add(3, 2);

        assert_eq!(p, 5);
        // missing a semicolon next line
        assert_eq!(add(2, 2), 4)
        assert_eq!(add(5, 0), 5);
        let result = add(2, 2);
        assert_eq!(result, 4);
    }
}

yields

error: expected `;`, found `assert_eq`
  --> src/lib.rs:15:33
   |
15 |         assert_eq!(add(2, 2), 4)
   |                                 ^ help: add `;` here
16 |         assert_eq!(add(5, 0), 5);
   |         --------- unexpected token

error: could not compile `test_lib` (lib) due to 1 previous error

Which is correct (a good message).

[smanilov]

In case it helps, here's a backtrace:

   0: <rustc_parse::parser::Parser>::parse_mod                                                
   1: <rustc_parse::parser::Parser>::parse_crate_mod                                                    
   2: rustc_interface::passes::parse                                                                    
   3: rustc_interface::interface::run_compiler::<(), rustc_driver_impl::run_compiler::{closure#0}>::{closure#1}                                                                                                 
   4: <scoped_tls::ScopedKey<rustc_span::SessionGlobals>>::set::<rustc_interface::util::run_in_thread_with_globals<rustc_interface::util::run_in_thread_pool_with_globals<rustc_interface::interface::run_compiler<(), rustc_driver_impl::run_compiler::{closure#0}>::{closure#1}, ()>::{closure#0}, ()>::{closure#0}::{closure#0}::{closure#0}, ()>
   5: rustc_span::create_session_globals_then::<(), rustc_interface::util::run_in_thread_with_globals<rustc_interface::util::run_in_thread_pool_with_globals<rustc_interface::interface::run_compiler<(), rustc_driver_impl::run_compiler::{closure#0}>::{closure#1}, ()>::{closure#0}, ()>::{closure#0}::{closure#0}::{closure#0}>

The message is generated in fn parse_mod at compiler/rustc_parse/src/parser/item.rs:90.