Rollup merge of rust-lang#132748 - lolbinarycat:rustdoc-intra-doc-link-warn-more-54191, r=GuillaumeGomez

get rid of some false negatives in rustdoc::broken_intra_doc_links

rustdoc will not try to do intra-doc linking if the "path" of a link looks too much like a "real url".

however, only inline links (`[text](url)`) can actually contain a url, other types of links (reference links, shortcut links) contain a *reference* which is later resolved to an actual url.

the "path" in this case cannot be a url, and therefore it should not be skipped due to looking like a url.

fixes rust-lang#54191

to minimize the number of false positives that will be introduced, the following heuristic is used:

If there's no backticks, be lenient revert to old behavior.
This is to prevent churn by linting on stuff that isn't meant to be a link.
only shortcut links have simple enough syntax that they
are likely to be written accidentlly, collapsed and reference links
need 4 metachars, and reference links will not usually use
backticks in the reference name.
therefore, only shortcut syntax gets the lenient behavior.
here's a truth table for how link kinds that cannot be urls are handled:

|              |  is shortcut link  | not shortcut link |
|--------------|--------------------|-------------------|
| has backtick |    never ignore    |    never ignore   |
| no backtick  | ignore if url-like |    never ignore   |

Author: fmease

src/librustdoc/passes/collect_intra_doc_links.rs

@@ -941,13 +941,21 @@ fn preprocess_link(
     ori_link: &MarkdownLink,
     dox: &str,
 ) -> Option<Result<PreprocessingInfo, PreprocessingError>> {
+    // certain link kinds cannot have their path be urls,
+    // so they should not be ignored, no matter how much they look like urls.
+    // e.g. [https://example.com/] is not a link to example.com.
+    let can_be_url = !matches!(
+        ori_link.kind,
+        LinkType::ShortcutUnknown | LinkType::CollapsedUnknown | LinkType::ReferenceUnknown
+    );
+
     // [] is mostly likely not supposed to be a link
     if ori_link.link.is_empty() {
         return None;
     }
 
     // Bail early for real links.
-    if ori_link.link.contains('/') {
+    if can_be_url && ori_link.link.contains('/') {
         return None;
     }
 
@@ -972,7 +980,7 @@ fn preprocess_link(
         Ok(None) => (None, link, link),
         Err((err_msg, relative_range)) => {
             // Only report error if we would not have ignored this link. See issue #83859.
-            if !should_ignore_link_with_disambiguators(link) {
+            if !(can_be_url && should_ignore_link_with_disambiguators(link)) {
                 let disambiguator_range = match range_between_backticks(&ori_link.range, dox) {
                     MarkdownLinkRange::Destination(no_backticks_range) => {
                         MarkdownLinkRange::Destination(
@@ -989,7 +997,25 @@ fn preprocess_link(
         }
     };
 
-    if should_ignore_link(path_str) {
+    // If there's no backticks, be lenient and revert to the old behavior.
+    // This is to prevent churn by linting on stuff that isn't meant to be a link.
+    // only shortcut links have simple enough syntax that they
+    // are likely to be written accidentally, collapsed and reference links
+    // need 4 metachars, and reference links will not usually use
+    // backticks in the reference name.
+    // therefore, only shortcut syntax gets the lenient behavior.
+    //
+    // here's a truth table for how link kinds that cannot be urls are handled:
+    //
+    // |-------------------------------------------------------|
+    // |              |  is shortcut link  | not shortcut link |
+    // |--------------|--------------------|-------------------|
+    // | has backtick |    never ignore    |    never ignore   |
+    // | no backtick  | ignore if url-like |    never ignore   |
+    // |-------------------------------------------------------|
+    let ignore_urllike =
+        can_be_url || (ori_link.kind == LinkType::ShortcutUnknown && !ori_link.link.contains('`'));
+    if ignore_urllike && should_ignore_link(path_str) {
         return None;
     }
 

tests/rustdoc-ui/disambiguator-endswith-named-suffix.rs

@@ -2,67 +2,67 @@
 //@ normalize-stderr: "nightly|beta|1\.[0-9][0-9]\.[0-9]" -> "$$CHANNEL"
 
 //! [struct@m!()]   //~ WARN: unmatched disambiguator `struct` and suffix `!()`
-//! [struct@m!{}]
+//! [struct@m!{}]   //~ WARN: unmatched disambiguator `struct` and suffix `!{}`
 //! [struct@m![]]
 //! [struct@f()]    //~ WARN: unmatched disambiguator `struct` and suffix `()`
 //! [struct@m!]     //~ WARN: unmatched disambiguator `struct` and suffix `!`
 //!
 //! [enum@m!()]     //~ WARN: unmatched disambiguator `enum` and suffix `!()`
-//! [enum@m!{}]
+//! [enum@m!{}]     //~ WARN: unmatched disambiguator `enum` and suffix `!{}`
 //! [enum@m![]]
 //! [enum@f()]      //~ WARN: unmatched disambiguator `enum` and suffix `()`
 //! [enum@m!]       //~ WARN: unmatched disambiguator `enum` and suffix `!`
 //!
 //! [trait@m!()]    //~ WARN: unmatched disambiguator `trait` and suffix `!()`
-//! [trait@m!{}]
+//! [trait@m!{}]    //~ WARN: unmatched disambiguator `trait` and suffix `!{}`
 //! [trait@m![]]
 //! [trait@f()]     //~ WARN: unmatched disambiguator `trait` and suffix `()`
 //! [trait@m!]      //~ WARN: unmatched disambiguator `trait` and suffix `!`
 //!
 //! [module@m!()]   //~ WARN: unmatched disambiguator `module` and suffix `!()`
-//! [module@m!{}]
+//! [module@m!{}]   //~ WARN: unmatched disambiguator `module` and suffix `!{}`
 //! [module@m![]]
 //! [module@f()]    //~ WARN: unmatched disambiguator `module` and suffix `()`
 //! [module@m!]     //~ WARN: unmatched disambiguator `module` and suffix `!`
 //!
 //! [mod@m!()]      //~ WARN: unmatched disambiguator `mod` and suffix `!()`
-//! [mod@m!{}]
+//! [mod@m!{}]      //~ WARN: unmatched disambiguator `mod` and suffix `!{}`
 //! [mod@m![]]
 //! [mod@f()]       //~ WARN: unmatched disambiguator `mod` and suffix `()`
 //! [mod@m!]        //~ WARN: unmatched disambiguator `mod` and suffix `!`
 //!
 //! [const@m!()]    //~ WARN: unmatched disambiguator `const` and suffix `!()`
-//! [const@m!{}]
+//! [const@m!{}]    //~ WARN: unmatched disambiguator `const` and suffix `!{}`
 //! [const@m![]]
 //! [const@f()]     //~ WARN: incompatible link kind for `f`
 //! [const@m!]      //~ WARN: unmatched disambiguator `const` and suffix `!`
 //!
 //! [constant@m!()]   //~ WARN: unmatched disambiguator `constant` and suffix `!()`
-//! [constant@m!{}]
+//! [constant@m!{}]   //~ WARN:  unmatched disambiguator `constant` and suffix `!{}`
 //! [constant@m![]]
 //! [constant@f()]    //~ WARN: incompatible link kind for `f`
 //! [constant@m!]     //~ WARN: unmatched disambiguator `constant` and suffix `!`
 //!
 //! [static@m!()]   //~ WARN: unmatched disambiguator `static` and suffix `!()`
-//! [static@m!{}]
+//! [static@m!{}]   //~ WARN: unmatched disambiguator `static` and suffix `!{}`
 //! [static@m![]]
 //! [static@f()]    //~ WARN: incompatible link kind for `f`
 //! [static@m!]     //~ WARN: unmatched disambiguator `static` and suffix `!`
 //!
 //! [function@m!()]   //~ WARN: unmatched disambiguator `function` and suffix `!()`
-//! [function@m!{}]
+//! [function@m!{}]   //~ WARN: unmatched disambiguator `function` and suffix `!{}`
 //! [function@m![]]
 //! [function@f()]
 //! [function@m!]     //~ WARN: unmatched disambiguator `function` and suffix `!`
 //!
 //! [fn@m!()]   //~ WARN: unmatched disambiguator `fn` and suffix `!()`
-//! [fn@m!{}]
+//! [fn@m!{}]   //~ WARN: unmatched disambiguator `fn` and suffix `!{}`
 //! [fn@m![]]
 //! [fn@f()]
 //! [fn@m!]     //~ WARN: unmatched disambiguator `fn` and suffix `!`
 //!
 //! [method@m!()]   //~ WARN: unmatched disambiguator `method` and suffix `!()`
-//! [method@m!{}]
+//! [method@m!{}]   //~ WARN: unmatched disambiguator `method` and suffix `!{}`
 //! [method@m![]]
 //! [method@f()]
 //! [method@m!]     //~ WARN: unmatched disambiguator `method` and suffix `!`
@@ -74,13 +74,13 @@
 //! [derive@m!]     //~ WARN: incompatible link kind for `m`
 //!
 //! [type@m!()]   //~ WARN: unmatched disambiguator `type` and suffix `!()`
-//! [type@m!{}]
+//! [type@m!{}]   //~ WARN: unmatched disambiguator `type` and suffix `!{}`
 //! [type@m![]]
 //! [type@f()]    //~ WARN: unmatched disambiguator `type` and suffix `()`
 //! [type@m!]     //~ WARN: unmatched disambiguator `type` and suffix `!`
 //!
 //! [value@m!()]   //~ WARN: unmatched disambiguator `value` and suffix `!()`
-//! [value@m!{}]
+//! [value@m!{}]   //~ WARN: unmatched disambiguator `value` and suffix `!{}`
 //! [value@m![]]
 //! [value@f()]
 //! [value@m!]     //~ WARN: unmatched disambiguator `value` and suffix `!`
@@ -92,13 +92,13 @@
 //! [macro@m!]
 //!
 //! [prim@m!()]   //~ WARN: unmatched disambiguator `prim` and suffix `!()`
-//! [prim@m!{}]
+//! [prim@m!{}]   //~ WARN: unmatched disambiguator `prim` and suffix `!{}`
 //! [prim@m![]]
 //! [prim@f()]    //~ WARN: unmatched disambiguator `prim` and suffix `()`
 //! [prim@m!]     //~ WARN: unmatched disambiguator `prim` and suffix `!`
 //!
 //! [primitive@m!()]   //~ WARN: unmatched disambiguator `primitive` and suffix `!()`
-//! [primitive@m!{}]
+//! [primitive@m!{}]   //~ WARN: unmatched disambiguator `primitive` and suffix `!{}`
 //! [primitive@m![]]
 //! [primitive@f()]    //~ WARN: unmatched disambiguator `primitive` and suffix `()`
 //! [primitive@m!]     //~ WARN: unmatched disambiguator `primitive` and suffix `!`