Include reason why a link is considered broken

Author: maxcnunes

clippy_lints/src/doc/broken_link.rs

@@ -6,17 +6,40 @@ use rustc_span::{BytePos, Span};
 use super::DOC_BROKEN_LINK;
 
 pub fn check(cx: &LateContext<'_>, attrs: &[Attribute]) {
-    for span in BrokenLinkLoader::collect_spans_broken_link(attrs) {
-        span_lint(cx, DOC_BROKEN_LINK, span, "possible broken doc link");
+    for broken_link in BrokenLinkLoader::collect_spans_broken_link(attrs) {
+        let reason_msg = match broken_link.reason {
+            BrokenLinkReason::MultipleLines => "broken across multiple lines",
+            BrokenLinkReason::MissingCloseParenthesis => "missing close parenthesis",
+            BrokenLinkReason::WhiteSpace => "whitespace within url",
+        };
+
+        span_lint(
+            cx,
+            DOC_BROKEN_LINK,
+            broken_link.span,
+            format!("possible broken doc link: {reason_msg}"),
+        );
     }
 }
 
+/// The reason why a link is considered broken.
+enum BrokenLinkReason {
+    MultipleLines,
+    MissingCloseParenthesis,
+    WhiteSpace,
+}
+
+/// Broken link data.
+struct BrokenLink {
+    reason: BrokenLinkReason,
+    span: Span,
+}
+
 /// Scan AST attributes looking up in doc comments for broken links
 /// which rustdoc won't be able to properly create link tags later.
-#[derive(Debug)]
 struct BrokenLinkLoader {
     /// List of spans for detected broken links.
-    spans_broken_link: Vec<Span>,
+    broken_links: Vec<BrokenLink>,
 
     /// Mark it has detected a link and it is processing whether
     /// or not it is broken.
@@ -51,9 +74,9 @@ struct BrokenLinkLoader {
 
 impl BrokenLinkLoader {
     /// Return spans of broken links.
-    fn collect_spans_broken_link(attrs: &[Attribute]) -> Vec<Span> {
+    fn collect_spans_broken_link(attrs: &[Attribute]) -> Vec<BrokenLink> {
         let mut loader = BrokenLinkLoader {
-            spans_broken_link: vec![],
+            broken_links: vec![],
             active: false,
             active_pos_start: 0,
             active_span: None,
@@ -65,7 +88,7 @@ impl BrokenLinkLoader {
             start: 0_u32,
         };
         loader.scan_attrs(attrs);
-        loader.spans_broken_link
+        loader.broken_links
     }
 
     fn scan_attrs(&mut self, attrs: &[Attribute]) {
@@ -79,15 +102,15 @@ impl BrokenLinkLoader {
                 if idx > 0 && self.active && self.processing_link_url {
                     let prev_attr = &attrs[idx - 1];
                     let prev_end_line = prev_attr.span.hi().0;
-                    self.record_broken_link(prev_end_line);
+                    self.record_broken_link(prev_end_line, BrokenLinkReason::MissingCloseParenthesis);
                 }
                 self.reset_lookup();
             }
         }
 
         if self.active && self.processing_link_url {
             let last_end_line = attrs.last().unwrap().span.hi().0;
-            self.record_broken_link(last_end_line);
+            self.record_broken_link(last_end_line, BrokenLinkReason::MissingCloseParenthesis);
             self.reset_lookup();
         }
     }
@@ -139,7 +162,7 @@ impl BrokenLinkLoader {
                 if self.url_multiple_lines {
                     // +3 skips the opening delimiter and +1 to include the closing parethesis
                     let pos_end = attr_span.lo().0 + u32::try_from(pos).unwrap() + 4;
-                    self.record_broken_link(pos_end);
+                    self.record_broken_link(pos_end, BrokenLinkReason::MultipleLines);
                     self.reset_lookup();
                 }
                 self.reset_lookup();
@@ -148,7 +171,7 @@ impl BrokenLinkLoader {
 
             if self.reading_link_url && c.is_whitespace() {
                 let pos_end = u32::try_from(pos).unwrap();
-                self.record_broken_link(pos_end);
+                self.record_broken_link(pos_end, BrokenLinkReason::WhiteSpace);
                 self.reset_lookup();
                 continue;
             }
@@ -173,14 +196,14 @@ impl BrokenLinkLoader {
         self.url_multiple_lines = false;
     }
 
-    fn record_broken_link(&mut self, pos_end: u32) {
+    fn record_broken_link(&mut self, pos_end: u32, reason: BrokenLinkReason) {
         if let Some(attr_span) = self.active_span {
             let start = BytePos(self.active_pos_start);
             let end = BytePos(pos_end);
 
-            let com_span = Span::new(start, end, attr_span.ctxt(), attr_span.parent());
+            let span = Span::new(start, end, attr_span.ctxt(), attr_span.parent());
 
-            self.spans_broken_link.push(com_span);
+            self.broken_links.push(BrokenLink { reason, span });
         }
     }
 }

tests/ui/doc_broken_link.rs

@@ -40,26 +40,32 @@ pub fn doc_valid_link_broken_url_tag_three_lines() {}
 /// Test invalid link, url part broken across multiple lines.
 /// [doc invalid link broken url scheme part part](https://
 /// test.fake/doc_invalid_link_broken_url_scheme_part)
-//~^^ ERROR: possible broken doc link
+//~^^ ERROR: possible broken doc link: broken across multiple lines
 pub fn doc_invalid_link_broken_url_scheme_part() {}
 
 /// Test invalid link, url part broken across multiple lines.
 /// [doc invalid link broken url host part](https://test
 /// .fake/doc_invalid_link_broken_url_host_part)
-//~^^ ERROR: possible broken doc link
+//~^^ ERROR: possible broken doc link: broken across multiple lines
 pub fn doc_invalid_link_broken_url_host_part() {}
 
-/// Test invalid link, url part broken across multiple lines.
-/// [doc invalid link broken url host part](
-/// https://test.fake/doc_invalid_link_missing_close_parenthesis
-//~^^ ERROR: possible broken doc link
-pub fn doc_invalid_link_missing_close_parenthesis() {}
-
 // NOTE: We don't test doc links where the url is broken accross
 // multiple lines in the path part because that is something
 // rustdoc itself will check and warn about it.
 pub fn doc_invalid_link_broken_url_path_part() {}
 
+/// Test invalid link, url missing close parenthesis.
+/// [doc invalid link broken url missing close parenthesis](
+/// https://test.fake/doc_invalid_link_missing_close_parenthesis
+//~^^ ERROR: possible broken doc link: missing close parenthesis
+pub fn doc_invalid_link_missing_close_parenthesis() {}
+
+/// Test invalid link, url whitespace within url.
+/// [doc invalid link broken url whitespace within url](
+/// https://test.fake/doc_invalid_link_url whitespace_within_url)
+//~^^ ERROR: possible broken doc link: whitespace within url
+pub fn doc_invalid_link_url_whitespace_within_url() {}
+
 /// This might be considered a link false positive
 /// and should be ignored by this lint rule:
 /// Example of referencing some code with brackets [FakeType].

tests/ui/doc_broken_link.stderr

@@ -1,4 +1,4 @@
-error: possible broken doc link
+error: possible broken doc link: broken across multiple lines
   --> tests/ui/doc_broken_link.rs:41:5
    |
 LL |   /// [doc invalid link broken url scheme part part](https://
@@ -9,21 +9,28 @@ LL | | /// test.fake/doc_invalid_link_broken_url_scheme_part)
    = note: `-D clippy::doc-broken-link` implied by `-D warnings`
    = help: to override `-D warnings` add `#[allow(clippy::doc_broken_link)]`
 
-error: possible broken doc link
+error: possible broken doc link: broken across multiple lines
   --> tests/ui/doc_broken_link.rs:47:5
    |
 LL |   /// [doc invalid link broken url host part](https://test
    |  _____^
 LL | | /// .fake/doc_invalid_link_broken_url_host_part)
    | |________________________________________________^
 
-error: possible broken doc link
-  --> tests/ui/doc_broken_link.rs:53:5
+error: possible broken doc link: missing close parenthesis
+  --> tests/ui/doc_broken_link.rs:58:5
    |
-LL |   /// [doc invalid link broken url host part](
+LL |   /// [doc invalid link broken url missing close parenthesis](
    |  _____^
 LL | | /// https://test.fake/doc_invalid_link_missing_close_parenthesis
    | |________________________________________________________________^
 
-error: aborting due to 3 previous errors
+error: possible broken doc link: whitespace within url
+  --> /Users/maxnunes/Development/forks/rust-clippy/tests/clippy.toml:1:40
+   |
+LL |   # default config for tests, overrides clippy.toml at the project root
+   |  ________________________________________^
+...  |
+
+error: aborting due to 4 previous errors