rustdoc does not warn about broken links if they contain . or []

[whatisaphone]

I got a PR yesterday that included something like this:

/// The tour de force of my career is [`foo.bar()`]
pub mod foo {
    pub fn bar() {}
}

In the current nightly rustdoc, foo.bar() neither resolves nor warns:

Our CI with --deny warnings did not catch this mistake (although I did 😄). I think rustdoc should trigger intra-doc-link-resolution-failure for this case.

[GuillaumeGomez]

The resolution failure is expected (should have been foo::bar) however, no warning is strange. I think it considers it as a path (as in a url) because of the ..

[QuietMisdreavus]

This is caused by this section of the intra-doc link code:

rust/src/librustdoc/passes/collect_intra_doc_links.rs

Lines 356 to 359 in 15d7704

	if path_str.contains(|ch: char| !(ch.is_alphanumeric() ||
	ch == ':' || ch == '_')) {
	continue;
	}

I think the idea here is that because of the dot, the link could be to a file, so it doesn't try to check it. (There's a similar skip earlier in the loop for if the link contains /.)

[jyn514]

@dylni mentioned in #77199 that this also applies to things like [&[String]], because of the brackets; it would be nice to warn about those. I know @Manishearth has been concerned in the past about warning too much in case it has false positives - maybe we could make this a new opt-in lint? as a bikeshed warn(rustdoc::strange_intra_doc_links) seems ok

[Manishearth]

I suspect a thing we can do is unconditionally hit the intra doc resolution path if it has backticks in it, at least. I'd rather not introduce another lint; we should work on improving the diagnostic instead.

[Nemo157]

Can we check whether it resolved as a markdown link too?

[`foo.bar()`] is creating a link to an undefined reference `foo.bar()`, so should be warned about as a broken link whether it was intended to be an intra-doc link or not.

[jyn514]

@Nemo157 none of these links will ever resolve. . and [] are not paths and rustdoc doesn't special case them:

rust/src/librustdoc/passes/collect_intra_doc_links.rs

Lines 2206 to 2234 in 8b95491

	let prim = match path_str {
	"isize" => Isize,
	"i8" => I8,
	"i16" => I16,
	"i32" => I32,
	"i64" => I64,
	"i128" => I128,
	"usize" => Usize,
	"u8" => U8,
	"u16" => U16,
	"u32" => U32,
	"u64" => U64,
	"u128" => U128,
	"f32" => F32,
	"f64" => F64,
	"char" => Char,
	"bool" | "true" | "false" => Bool,
	"str" | "&str" => Str,
	// See #80181 for why these don't have symbols associated.
	"slice" => Slice,
	"array" => Array,
	"tuple" => Tuple,
	"unit" => Unit,
	"pointer" | "*const" | "*mut" => RawPointer,
	"reference" | "&" | "&mut" => Reference,
	"fn" => Fn,
	"never" | "!" => Never,
	_ => return None,
	};

[jyn514]

Oh, you mean as a URL. Hmm, maybe? I have to look back over the pulldown API.

[Nemo157]

The [foo] form does not link to a URL, it references a URL defined elsewhere inside the markdown document using the link label foo. If that label is not defined, I think technically it is not a link, it's just the text [foo]; but this is a syntax niche that intra-doc-links has already inserted itself into so I think it's fine for us to warn on all reference links that are missing a link reference definition (including the implicit intra-doc-links definitions).

[Manishearth]

@Nemo157 you misunderstand; we only hit this codepath for broken refs and for actual URLs. If it resolved to a markdown ref the ref title will never be seen here, though the URL passed to the ref title might (if it's sufficiently non-URLlike)

[Manishearth]

Oh, though I guess we could unconditionally warn on unresolving broken refs (but use the intra doc diagnostic on broken urls)

[lolbinarycat]

another case where these get confusing:

/// [whatever][1]
///
/// some other text
/// [1]: https://example.com/whatever

the [1]: does not actually get turned into a link reference, since there is no paragraph break before it.