Rustdoc should ignore unresolved imports in function bodies #97976

SpriteOvO · 2022-06-10T21:25:48Z

I tried this code:

Cargo.toml

[package]
name = "issue-demo"
version = "0.1.0"
edition = "2021"

[dependencies]

[target.'cfg(windows)'.dependencies]
winapi = { version = "0.3.9", features = ["debugapi"], optional = true }

src/main.rs

#[cfg(any(all(windows, feature = "winapi"), doc))]
fn doc_me() {
    use winapi::um::debugapi::OutputDebugStringW;

    let text = vec![0_u16];
    let text = text.as_ptr();
    unsafe { OutputDebugStringW(text) }
}

fn main() {
    println!("Hello, world!");
}

Run

cargo doc --all-features --open
# or
cargo +nightly doc --all-features --open

on platforms other than Windows.

I expected to see this happen: No errors in the terminal, the doc_me function should be displayed in the documentation page. (According to the Rustdoc documentation Interactions between platform-specific docs)

Instead, this happened: Terminal outputs error:

$ cargo +nightly doc --all-features
 Documenting issue-demo v0.1.0 (REDACTED/issue-proj)
error[E0433]: failed to resolve: use of undeclared crate or module `winapi`
 --> src/main.rs:3:9
  |
3 |     use winapi::um::debugapi::OutputDebugStringW;
  |         ^^^^^^ use of undeclared crate or module `winapi`

error: Compilation failed, aborting rustdoc

For more information about this error, try `rustc --explain E0433`.
error: could not document `issue-demo`

Caused by:
  process didn't exit successfully: `rustdoc --edition=2021 --crate-type bin --crate-name issue_demo src/main.rs -o REDACTED/issue-proj/target/doc --cfg 'feature="winapi"' --error-format=json --json=diagnostic-rendered-ansi,artifacts,future-incompat --document-private-items '-Arustdoc::private-intra-doc-links' -C metadata=9a8ace04a496849a -L dependency=REDACTED/issue-proj/target/debug/deps --crate-version 0.1.0` (exit status: 1)

If we change the code of src/main.rs to: (remove the use statement)

#[cfg(any(all(windows, feature = "winapi"), doc))]
fn doc_me() {
    let text = vec![0_u16];
    let text = text.as_ptr();
    unsafe { winapi::um::debugapi::OutputDebugStringW(text) }
}

fn main() {
    println!("Hello, world!");
}

It will work as expected.

Meta

rustc --version --verbose:

rustc 1.61.0 (fe5b13d68 2022-05-18)
binary: rustc
commit-hash: fe5b13d681f25ee6474be29d748c65adcd91f69e
commit-date: 2022-05-18
host: x86_64-unknown-linux-gnu
release: 1.61.0
LLVM version: 14.0.0

rustc +nightly --version --verbose:

rustc 1.63.0-nightly (420c970cb 2022-06-09)
binary: rustc
commit-hash: 420c970cb1edccbf60ff2aeb51ca01e2300b09ef
commit-date: 2022-06-09
host: x86_64-unknown-linux-gnu
release: 1.63.0-nightly
LLVM version: 14.0.5

The text was updated successfully, but these errors were encountered:

eggyal · 2022-06-10T22:36:43Z

You've included your stable rustc version, but the given instructions use nightly. Does the issue also exist on stable? If not, could you just confirm the nightly version at issue?

SpriteOvO · 2022-06-11T07:00:08Z

You've included your stable rustc version, but the given instructions use nightly. Does the issue also exist on stable? If not, could you just confirm the nightly version at issue?

@eggyal Yes, it is also exist on stable. Issue edited.

GuillaumeGomez · 2022-06-17T13:06:00Z

The problem isn't rustdoc here but your cfg. More precisely the doc inside. In here, rustdoc calls rustc so it can get information and rustc cannot find the import (as expected). You need to add the cfg on the import as well.

If I'm completely wrong about this, don't hesitate to reopen the issue. Closing it in the meantime.

SpriteOvO · 2022-06-17T13:12:12Z

The problem isn't rustdoc here but your cfg. More precisely the doc inside. In here, rustdoc calls rustc so it can get information and rustc cannot find the import (as expected). You need to add the cfg on the import as well.

If I'm completely wrong about this, don't hesitate to reopen the issue. Closing it in the meantime.

@GuillaumeGomez But Rustdoc promised in the Book:

To document your crate, Rustdoc only needs to know the public signature of your functions. In particular, it doesn't have to know how any of your functions are implemented, so it ignores all type errors and name resolution errors with function bodies.

This also covers import errors, doesn't it?

GuillaumeGomez · 2022-06-17T13:13:41Z

This is an interesting point. We need some information. This section should be updated. Reopening the issue then.

jyn514 · 2022-06-20T04:36:47Z

You can use -Ztreat-err-as-bug and RIST_BACKTRACE to find which query is invoking name resolution here.

SpriteOvO · 2022-06-21T19:25:11Z

@jyn514 This is output. I'm not sure, it still seems to be using pass instead of query? I didn't find an overrideable query named expansion. (Obviously I misunderstood something)

$ rustdoc +nightly src/main.rs -Ztreat-err-as-bug
error[E0433]: failed to resolve: maybe a missing crate `winapi`?
 --> src/main.rs:3:9
  |
3 |     use winapi::um::debugapi::OutputDebugStringW;
  |         ^^^^^^ maybe a missing crate `winapi`?
  |
  = help: consider adding `extern crate winapi` to use the `winapi` crate

thread 'rustc' panicked at 'aborting due to `-Z treat-err-as-bug=1`', compiler/rustc_errors/src/lib.rs:1449:27
stack backtrace:
   0:     0x7f8cb4a9e49d - std::backtrace_rs::backtrace::libunwind::trace::h38cae73bd792c877
                               at /rustc/cacc75c82ebe15cf63d31034fcf7f1016cddf0e2/library/std/src/../../backtrace/src/backtrace/libunwind.rs:93:5
   1:     0x7f8cb4a9e49d - std::backtrace_rs::backtrace::trace_unsynchronized::h8e053040b0b51451
                               at /rustc/cacc75c82ebe15cf63d31034fcf7f1016cddf0e2/library/std/src/../../backtrace/src/backtrace/mod.rs:66:5
   2:     0x7f8cb4a9e49d - std::sys_common::backtrace::_print_fmt::h31b97fe7e89502f9
                               at /rustc/cacc75c82ebe15cf63d31034fcf7f1016cddf0e2/library/std/src/sys_common/backtrace.rs:66:5
   3:     0x7f8cb4a9e49d - <std::sys_common::backtrace::_print::DisplayBacktrace as core::fmt::Display>::fmt::h5c671a6da31da332
                               at /rustc/cacc75c82ebe15cf63d31034fcf7f1016cddf0e2/library/std/src/sys_common/backtrace.rs:45:22
   4:     0x7f8cb4afa2dc - core::fmt::write::h41097386f3da9277
                               at /rustc/cacc75c82ebe15cf63d31034fcf7f1016cddf0e2/library/core/src/fmt/mod.rs:1196:17
   5:     0x7f8cb4a8fb01 - std::io::Write::write_fmt::hb65c9f86c8aba0db
                               at /rustc/cacc75c82ebe15cf63d31034fcf7f1016cddf0e2/library/std/src/io/mod.rs:1654:15
   6:     0x7f8cb4aa1175 - std::sys_common::backtrace::_print::hdc514304bc245eca
                               at /rustc/cacc75c82ebe15cf63d31034fcf7f1016cddf0e2/library/std/src/sys_common/backtrace.rs:48:5
   7:     0x7f8cb4aa1175 - std::sys_common::backtrace::print::h151e88258ea30387
                               at /rustc/cacc75c82ebe15cf63d31034fcf7f1016cddf0e2/library/std/src/sys_common/backtrace.rs:35:9
   8:     0x7f8cb4aa1175 - std::panicking::default_hook::{{closure}}::h73c1e663080d3f2d
                               at /rustc/cacc75c82ebe15cf63d31034fcf7f1016cddf0e2/library/std/src/panicking.rs:295:22
   9:     0x7f8cb4aa0e96 - std::panicking::default_hook::h7e38b1d6902bcb35
                               at /rustc/cacc75c82ebe15cf63d31034fcf7f1016cddf0e2/library/std/src/panicking.rs:314:9
  10:     0x7f8cb52fc051 - rustc_driver[a943fb23bb6f3d7]::DEFAULT_HOOK::{closure#0}::{closure#0}
  11:     0x7f8cb4aa184a - std::panicking::rust_panic_with_hook::h61964c46760a3d63
                               at /rustc/cacc75c82ebe15cf63d31034fcf7f1016cddf0e2/library/std/src/panicking.rs:702:17
  12:     0x7f8cb4aa1649 - std::panicking::begin_panic_handler::{{closure}}::h30113bf9b3b03d33
                               at /rustc/cacc75c82ebe15cf63d31034fcf7f1016cddf0e2/library/std/src/panicking.rs:586:13
  13:     0x7f8cb4a9e954 - std::sys_common::backtrace::__rust_end_short_backtrace::h62a1f4cef7db596d
                               at /rustc/cacc75c82ebe15cf63d31034fcf7f1016cddf0e2/library/std/src/sys_common/backtrace.rs:138:18
  14:     0x7f8cb4aa13b9 - rust_begin_unwind
                               at /rustc/cacc75c82ebe15cf63d31034fcf7f1016cddf0e2/library/std/src/panicking.rs:584:5
  15:     0x7f8cb4a662c3 - core::panicking::panic_fmt::h67caabfe06301e98
                               at /rustc/cacc75c82ebe15cf63d31034fcf7f1016cddf0e2/library/core/src/panicking.rs:142:14
  16:     0x7f8cb64a0dde - <rustc_errors[6bc7ce1ecb76dda5]::HandlerInner>::panic_if_treat_err_as_bug
  17:     0x7f8cb7d64699 - <rustc_errors[6bc7ce1ecb76dda5]::HandlerInner>::emit_diagnostic
  18:     0x7f8cb7d63c01 - <rustc_errors[6bc7ce1ecb76dda5]::Handler>::emit_diagnostic
  19:     0x7f8cb649fff9 - <rustc_errors[6bc7ce1ecb76dda5]::ErrorGuaranteed as rustc_errors[6bc7ce1ecb76dda5]::diagnostic_builder::EmissionGuarantee>::diagnostic_builder_emit_producing_guarantee
  20:     0x7f8cb575fd98 - <rustc_resolve[8675f4fc89cebd7c]::Resolver>::report_error
  21:     0x7f8cb779a3a8 - <rustc_resolve[8675f4fc89cebd7c]::imports::ImportResolver>::finalize_import
  22:     0x7f8cb7797e23 - <rustc_resolve[8675f4fc89cebd7c]::imports::ImportResolver>::finalize_imports
  23:     0x7f8cb779bd7b - <rustc_session[1f78975236c951ca]::session::Session>::time::<(), <rustc_resolve[8675f4fc89cebd7c]::Resolver>::resolve_crate::{closure#0}>
  24:     0x7f8cb74f018a - rustc_interface[230b39356bc6dc4e]::passes::configure_and_expand
  25:     0x7f8cb74e8863 - <rustc_interface[230b39356bc6dc4e]::queries::Queries>::expansion
  26:     0x561e71e2eaa0 - <rustc_interface[230b39356bc6dc4e]::interface::Compiler>::enter::<rustdoc[41ddfdff4ee9a4db]::main_options::{closure#0}::{closure#0}, core[4f3677c414e9e7a2]::result::Result<(), rustc_errors[6bc7ce1ecb76dda5]::ErrorGuaranteed>>
  27:     0x561e71cde33a - rustc_span[2a7938c1129556cc]::with_source_map::<core[4f3677c414e9e7a2]::result::Result<(), rustc_errors[6bc7ce1ecb76dda5]::ErrorGuaranteed>, rustc_interface[230b39356bc6dc4e]::interface::create_compiler_and_run<core[4f3677c414e9e7a2]::result::Result<(), rustc_errors[6bc7ce1ecb76dda5]::ErrorGuaranteed>, rustdoc[41ddfdff4ee9a4db]::main_options::{closure#0}>::{closure#1}>
  28:     0x561e71e312a1 - rustc_interface[230b39356bc6dc4e]::interface::create_compiler_and_run::<core[4f3677c414e9e7a2]::result::Result<(), rustc_errors[6bc7ce1ecb76dda5]::ErrorGuaranteed>, rustdoc[41ddfdff4ee9a4db]::main_options::{closure#0}>
  29:     0x561e71ce267f - <scoped_tls[9b0a97b116fbaba]::ScopedKey<rustc_span[2a7938c1129556cc]::SessionGlobals>>::set::<rustdoc[41ddfdff4ee9a4db]::main_args::{closure#0}, core[4f3677c414e9e7a2]::result::Result<(), rustc_errors[6bc7ce1ecb76dda5]::ErrorGuaranteed>>
  30:     0x561e71e5933f - std[453ac8ab9b5fa23e]::sys_common::backtrace::__rust_begin_short_backtrace::<rustc_interface[230b39356bc6dc4e]::util::run_in_thread_pool_with_globals<rustdoc[41ddfdff4ee9a4db]::main_args::{closure#0}, core[4f3677c414e9e7a2]::result::Result<(), rustc_errors[6bc7ce1ecb76dda5]::ErrorGuaranteed>>::{closure#0}, core[4f3677c414e9e7a2]::result::Result<(), rustc_errors[6bc7ce1ecb76dda5]::ErrorGuaranteed>>
  31:     0x561e71f49359 - <<std[453ac8ab9b5fa23e]::thread::Builder>::spawn_unchecked_<rustc_interface[230b39356bc6dc4e]::util::run_in_thread_pool_with_globals<rustdoc[41ddfdff4ee9a4db]::main_args::{closure#0}, core[4f3677c414e9e7a2]::result::Result<(), rustc_errors[6bc7ce1ecb76dda5]::ErrorGuaranteed>>::{closure#0}, core[4f3677c414e9e7a2]::result::Result<(), rustc_errors[6bc7ce1ecb76dda5]::ErrorGuaranteed>>::{closure#1} as core[4f3677c414e9e7a2]::ops::function::FnOnce<()>>::call_once::{shim:vtable#0}
  32:     0x7f8cb4aab783 - <alloc::boxed::Box<F,A> as core::ops::function::FnOnce<Args>>::call_once::ha95224ff040ea8fe
                               at /rustc/cacc75c82ebe15cf63d31034fcf7f1016cddf0e2/library/alloc/src/boxed.rs:1951:9
  33:     0x7f8cb4aab783 - <alloc::boxed::Box<F,A> as core::ops::function::FnOnce<Args>>::call_once::h2429363f7b78f055
                               at /rustc/cacc75c82ebe15cf63d31034fcf7f1016cddf0e2/library/alloc/src/boxed.rs:1951:9
  34:     0x7f8cb4aab783 - std::sys::unix::thread::Thread::new::thread_start::h00f780f864797841
                               at /rustc/cacc75c82ebe15cf63d31034fcf7f1016cddf0e2/library/std/src/sys/unix/thread.rs:108:17
  35:     0x7f8cb488054d - <unknown>
  36:     0x7f8cb4905874 - clone
  37:                0x0 - <unknown>

error: internal compiler error: unexpected panic

note: the compiler unexpectedly panicked. this is a bug.

note: we would appreciate a bug report: https://github.com/rust-lang/rust/issues/new?labels=C-bug%2C+I-ICE%2C+T-compiler&template=ice.md

note: rustc 1.63.0-nightly (cacc75c82 2022-06-16) running on x86_64-unknown-linux-gnu

note: compiler flags: -Z treat-err-as-bug

query stack during panic:
end of query stack

jyn514 · 2022-06-22T05:03:19Z

It looks like I missed this in #73566. I only ignored errors in late resolution, not early imports:

rust/compiler/rustc_resolve/src/lib.rs

Lines 1545 to 1550 in 3a8b014

 self.session.time("finalize_imports", || ImportResolver { r: self }.finalize_imports()); 

 self.session.time("resolve_access_levels", || { 

 AccessLevelsVisitor::compute_access_levels(self, krate) 

 }); 

 self.session.time("finalize_macro_resolutions", || self.finalize_macro_resolutions()); 

 self.session.time("late_resolve_crate", || self.late_resolve_crate(krate));

A workaround in the meantime is to avoid use statements that don't resolve:

#[cfg(any(all(windows, feature = "winapi"), doc))]
fn doc_me() {
    let text = vec![0_u16];
    let text = text.as_ptr();
    unsafe { winapi::um::debugapi::OutputDebugStringW(text) }
}

jyn514 · 2022-06-22T05:17:51Z

Honestly, if no one has noticed this until now, I'm inclined to just leave it broken - this entire "feature" is a giant hack anyway.

jyn514 · 2023-01-04T18:44:36Z

I'm going to close this, I don't think it was ever supported even with everybody_loops and we document the limitation in https://doc.rust-lang.org/beta/rustdoc/advanced-features.html#interactions-between-platform-specific-docs.

SpriteOvO added the C-bug Category: This is a bug. label Jun 10, 2022

notriddle added the T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue. label Jun 10, 2022

GuillaumeGomez closed this as completed Jun 17, 2022

GuillaumeGomez reopened this Jun 17, 2022

jyn514 closed this as not planned Won't fix, can't repro, duplicate, stale Jan 4, 2023

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Rustdoc should ignore unresolved imports in function bodies #97976

Rustdoc should ignore unresolved imports in function bodies #97976

SpriteOvO commented Jun 10, 2022 •

edited

Loading

eggyal commented Jun 10, 2022

SpriteOvO commented Jun 11, 2022

GuillaumeGomez commented Jun 17, 2022

SpriteOvO commented Jun 17, 2022

GuillaumeGomez commented Jun 17, 2022

jyn514 commented Jun 20, 2022 •

edited

Loading

SpriteOvO commented Jun 21, 2022 •

edited

Loading

jyn514 commented Jun 22, 2022 •

edited

Loading

jyn514 commented Jun 22, 2022

jyn514 commented Jan 4, 2023

Rustdoc should ignore unresolved imports in function bodies #97976

Rustdoc should ignore unresolved imports in function bodies #97976

Comments

SpriteOvO commented Jun 10, 2022 • edited Loading

Meta

eggyal commented Jun 10, 2022

SpriteOvO commented Jun 11, 2022

GuillaumeGomez commented Jun 17, 2022

SpriteOvO commented Jun 17, 2022

GuillaumeGomez commented Jun 17, 2022

jyn514 commented Jun 20, 2022 • edited Loading

SpriteOvO commented Jun 21, 2022 • edited Loading

jyn514 commented Jun 22, 2022 • edited Loading

jyn514 commented Jun 22, 2022

jyn514 commented Jan 4, 2023

SpriteOvO commented Jun 10, 2022 •

edited

Loading

jyn514 commented Jun 20, 2022 •

edited

Loading

SpriteOvO commented Jun 21, 2022 •

edited

Loading

jyn514 commented Jun 22, 2022 •

edited

Loading