rustdoc panics on broken intra-doc links if there are both inner and outer attributes

[yvt]

src/lib.rs:

macro_rules! m {
    () => {
        /// A
        pub mod mymodule;
    }
}

m!();

src/mymodule.rs:

//! [`long_cat`] is really long

Full source code

I expected to see this happen: cargo doc completes successfully with a "unresolved link to long_cat" warning

Instead, this happened: thread 'rustc' panicked at 'could not find markdown in source', src/librustdoc/passes/mod.rs:199:48

Meta

rustc --version --verbose:

rustc 1.49.0-nightly (31530e5d1 2020-10-20)
binary: rustc
commit-hash: 31530e5d132ebcc3654baf2e5460599681520af0
commit-date: 2020-10-20
host: x86_64-apple-darwin
release: 1.49.0-nightly
LLVM version: 11.0

Backtrace

thread 'rustc' panicked at 'could not find markdown in source', src/librustdoc/passes/mod.rs:199:48
stack backtrace:
   0: _rust_begin_unwind
   1: core::panicking::panic_fmt
   2: core::option::expect_failed
   3: rustdoc::passes::source_span_for_markdown_range
   4: core::ops::function::FnOnce::call_once{{vtable.shim}}
   5: rustc_middle::lint::struct_lint_level::struct_lint_level_impl
   6: rustc_middle::ty::context::TyCtxt::struct_span_lint_hir
   7: rustdoc::passes::collect_intra_doc_links::resolution_failure
   8: rustdoc::passes::collect_intra_doc_links::LinkCollector::resolve_link
   9: <rustdoc::passes::collect_intra_doc_links::LinkCollector as rustdoc::fold::DocFolder>::fold_item
  10: <alloc::vec::Vec<T> as alloc::vec::SpecFromIter<T,I>>::from_iter
  11: rustdoc::fold::DocFolder::fold_inner_recur
  12: rustdoc::fold::DocFolder::fold_item_recur
  13: <rustdoc::passes::collect_intra_doc_links::LinkCollector as rustdoc::fold::DocFolder>::fold_item
  14: rustdoc::passes::collect_intra_doc_links::collect_intra_doc_links
  15: rustdoc::core::run_global_ctxt
  16: rustc_interface::passes::QueryContext::enter
  17: rustc_interface::interface::create_compiler_and_run
  18: rustdoc::core::run_core
  19: rustdoc::main_options
  20: rustc_span::with_session_globals
note: Some details are omitted, run with `RUST_BACKTRACE=full` for a verbose backtrace.

error: internal compiler error: unexpected panic

error: Unrecognized option: 'crate-version'

error: could not document `rust-bug-202010`

[jyn514]

I bet the source span is wrong somehow.

[jyn514]

The issue is that the documentation on the re-export is being combined with the original documentation. collect_intra_doc_links splits it up by the module it's scoped to, which is different for the two doc-comments; if you remove /// A it works fine. collect_intra_doc_links needs to only pass the documentation for the current scope to source_span_for_markdown_range, not the combined docs.

Not sure why it needs a separate file.

[jyn514]

The markdown range it comes up with is 3..13. Hmm, this is weird - I think this is actually the correct span because they both come from markdown_links, which doesn't care about scoping and just works on strings. Maybe it is a bug in span_for_markdown_range after all?

[jyn514]

Aha, here we go: span_for_range is trying to look at the rustc snippet instead of the text it was provided.

2:rustcTRACE rustdoc::passes markdown is A
2:rustc[`long_cat`] is really long
2:rustcTRACE rustdoc::passes snippet is /// A
thread 'rustc' panicked at 'could not find markdown range 3..13 in source', src/librustdoc/passes/mod
.rs:202:36

diff --git a/src/librustdoc/passes/mod.rs b/src/librustdoc/passes/mod.rs
index 2591650e3f9..ec1e2ae36e6 100644
--- a/src/librustdoc/passes/mod.rs
+++ b/src/librustdoc/passes/mod.rs
@@ -179,7 +179,9 @@ crate fn source_span_for_markdown_range(
         return None;
     }
 
+    trace!("markdown is {}", markdown);
     let snippet = cx.sess().source_map().span_to_snippet(span_of_attrs(attrs)?).ok()?;
+    trace!("snippet is {}", snippet);

Maybe it could just work with markdown instead?

[jyn514]

Hmm, there are some other bugs here too: normally rustdoc will resolve //! docs in the scope inside the module and /// to the scope of the parent. But since there are inner docs, it will resolve all of the links inside the module. I think the fix for both the issues is to separate outer docs from inner ones; not yet sure how to do that.

[jonhoo]

To add another test-case for what I believe is another instance of the same problem:

#[warn(rustdoc::broken_intra_doc_links)]

/// We have some module docs here.
pub mod foo {
    //! [`Foo`]
    //!
    //! And some more module docs here.
    pub struct Foo;
}

This doesn't panic, but produces:

warning: unresolved link to `Foo`
 --> src/lib.rs:5:11
  |
5 |     //! [`Foo`]
  |           ^^^ no item named `Foo` in scope
  |
note: the lint level is defined here
 --> src/lib.rs:1:8
  |
1 | #[warn(rustdoc::broken_intra_doc_links)]
  |        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  = help: to escape `[` and `]` characters, add '\' before them like `\[` or `\]`

For an even more confused case, split the module into its own file:

#[warn(rustdoc::broken_intra_doc_links)]

/// We have some module docs here.
pub mod foo;

//! And some more module docs here.
//! [`Foo`]
pub struct Foo;

Which yields this nonsensical warning:

warning: unresolved link to `Foo`
 --> src/lib.rs:3:1
  |
2 | |
  | |___________^
3 | / /// We have some module docs here.
  |
note: the lint level is defined here
 --> src/lib.rs:1:8
  |
1 | #[warn(rustdoc::broken_intra_doc_links)]
  |        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  = note: the link appears in this line:

          [`Foo`]
           ^^^^^
  = note: no item named `Foo` in scope
  = help: to escape `[` and `]` characters, add '\' before them like `\[` or `\]`

Essentially, the span of the unresolved link is misattributed to the wrong file. The line and column values are correct, it's just the wrong file that's used.

[jyn514]

This doesn't panic, but produces:

That's #78591 (comment).

rust/src/librustdoc/passes/collect_intra_doc_links.rs

Line 899 in 8ceea01

let inner_docs = item.inner_docs(self.cx.tcx);

is assuming there is only inner or outer docs, not both.