doc_comments_missing_terminal_punctuation: treat some trailers as unfixable

AudaciousAxiom · AudaciousAxiom · commit 0df651d6ed25 · 2025-10-02T23:11:01.000+02:00
diff --git a/clippy_lints/src/doc/doc_comments_missing_terminal_punctuation.rs b/clippy_lints/src/doc/doc_comments_missing_terminal_punctuation.rs
@@ -10,29 +10,45 @@ const MSG: &str = "doc comments should end with a terminal punctuation mark";
 const PUNCTUATION_SUGGESTION: char = '.';
 
 pub fn check(cx: &LateContext<'_>, doc: &str, fragments: Fragments<'_>) {
-    // This ignores `#[doc]` attributes, which we do not handle.
-    if let Some(offset) = is_missing_punctuation(doc)
-        && let Some(span) = fragments.span(cx, offset..offset)
-    {
-        clippy_utils::diagnostics::span_lint_and_sugg(
-            cx,
-            DOC_COMMENTS_MISSING_TERMINAL_PUNCTUATION,
-            span,
-            MSG,
-            "end the doc comment with some punctuation",
-            PUNCTUATION_SUGGESTION.to_string(),
-            Applicability::MaybeIncorrect,
-        );
+    match is_missing_punctuation(doc) {
+        IsMissingPunctuation::Fixable(offset) => {
+            // This ignores `#[doc]` attributes, which we do not handle.
+            if let Some(span) = fragments.span(cx, offset..offset) {
+                clippy_utils::diagnostics::span_lint_and_sugg(
+                    cx,
+                    DOC_COMMENTS_MISSING_TERMINAL_PUNCTUATION,
+                    span,
+                    MSG,
+                    "end the doc comment with some punctuation",
+                    PUNCTUATION_SUGGESTION.to_string(),
+                    Applicability::MaybeIncorrect,
+                );
+            }
+        },
+        IsMissingPunctuation::Unfixable(offset) => {
+            // This ignores `#[doc]` attributes, which we do not handle.
+            if let Some(span) = fragments.span(cx, offset..offset) {
+                clippy_utils::diagnostics::span_lint_and_help(
+                    cx,
+                    DOC_COMMENTS_MISSING_TERMINAL_PUNCTUATION,
+                    span,
+                    MSG,
+                    None,
+                    "end the doc comment with some punctuation",
+                );
+            }
+        },
+        IsMissingPunctuation::No => {},
     }
 }
 
 #[must_use]
 /// If punctuation is missing, returns the offset where new punctuation should be inserted.
-fn is_missing_punctuation(doc_string: &str) -> Option<usize> {
+fn is_missing_punctuation(doc_string: &str) -> IsMissingPunctuation {
     const TERMINAL_PUNCTUATION_MARKS: &[char] = &['.', '?', '!', '…'];
 
     let mut no_report_depth = 0;
-    let mut text_offset = None;
+    let mut missing_punctuation = IsMissingPunctuation::No;
     for (event, offset) in
         Parser::new_ext(doc_string, main_body_opts() - Options::ENABLE_SMART_PUNCTUATION).into_offset_iter()
     {
@@ -54,35 +70,48 @@ fn is_missing_punctuation(doc_string: &str) -> Option<usize> {
                 TagEnd::CodeBlock | TagEnd::Heading(_) | TagEnd::HtmlBlock | TagEnd::List(_) | TagEnd::Table,
             ) => {
                 no_report_depth -= 1;
-                text_offset = None;
+                missing_punctuation = IsMissingPunctuation::No;
             },
             Event::InlineHtml(_) | Event::Start(Tag::Image { .. }) | Event::End(TagEnd::Image) => {
-                text_offset = None;
+                missing_punctuation = IsMissingPunctuation::No;
             },
             Event::Code(..) | Event::Start(Tag::Link { .. }) | Event::End(TagEnd::Link)
                 if no_report_depth == 0 && !offset.is_empty() =>
             {
-                text_offset = Some(offset.end);
+                if doc_string[..offset.end]
+                    .trim_end()
+                    .ends_with(TERMINAL_PUNCTUATION_MARKS)
+                {
+                    missing_punctuation = IsMissingPunctuation::No;
+                } else {
+                    missing_punctuation = IsMissingPunctuation::Fixable(offset.end);
+                }
             },
             Event::Text(..) if no_report_depth == 0 && !offset.is_empty() => {
-                // American-style quotes require punctuation to be placed inside closing quotation marks.
-                if doc_string[..offset.end].trim_end().ends_with('"') {
-                    text_offset = Some(offset.end - 1);
+                let trimmed = doc_string[..offset.end].trim_end();
+                if trimmed.ends_with(TERMINAL_PUNCTUATION_MARKS) {
+                    missing_punctuation = IsMissingPunctuation::No;
+                } else if let Some(t) = trimmed.strip_suffix(|c| c == ')' || c == '"') {
+                    if t.ends_with(TERMINAL_PUNCTUATION_MARKS) {
+                        // Avoid false positives.
+                        missing_punctuation = IsMissingPunctuation::No;
+                    } else {
+                        missing_punctuation = IsMissingPunctuation::Unfixable(offset.end);
+                    }
                 } else {
-                    text_offset = Some(offset.end);
+                    missing_punctuation = IsMissingPunctuation::Fixable(offset.end);
                 }
             },
             _ => {},
         }
     }
 
-    let text_offset = text_offset?;
-    if doc_string[..text_offset]
-        .trim_end()
-        .ends_with(TERMINAL_PUNCTUATION_MARKS)
-    {
-        None
-    } else {
-        Some(text_offset)
-    }
+    missing_punctuation
+}
+
+#[derive(Debug, Copy, Clone, PartialEq, Eq)]
+enum IsMissingPunctuation {
+    Fixable(usize),
+    Unfixable(usize),
+    No,
 }
diff --git a/tests/ui/doc/doc_comments_missing_terminal_punctuation.fixed b/tests/ui/doc/doc_comments_missing_terminal_punctuation.fixed
@@ -80,12 +80,10 @@ mod module {
 }
 
 enum Trailers {
-    /// Sometimes the doc comment ends with parentheses (like this).
-    //~^ doc_comments_missing_terminal_punctuation
-    EndsWithParens,
-    /// (Sometimes the last sentence is in parentheses, but there is no special treatment of this.).
-    //~^ doc_comments_missing_terminal_punctuation
-    ParensFailing,
+    /// Sometimes the last sentence ends with parentheses (and that's ok).
+    ParensPassing,
+    /// (Sometimes the last sentence is in parentheses.)
+    SentenceInParensPassing,
     /// **Sometimes the last sentence is in bold, and that's ok.**
     DoubleStarPassing,
     /// **But sometimes it is missing a period.**
@@ -97,10 +95,9 @@ enum Trailers {
     //~^ doc_comments_missing_terminal_punctuation
     UnderscoreFailing,
     /// This comment ends with "a quote."
-    QuotePassing,
-    /// This comment ends with "a quote."
-    //~^ doc_comments_missing_terminal_punctuation
-    QuoteFailing,
+    AmericanStyleQuotePassing,
+    /// This comment ends with "a quote".
+    BritishStyleQuotePassing,
 }
 
 /// Doc comments can end with an [inline link](#anchor).
diff --git a/tests/ui/doc/doc_comments_missing_terminal_punctuation.rs b/tests/ui/doc/doc_comments_missing_terminal_punctuation.rs
@@ -80,12 +80,10 @@ mod module {
 }
 
 enum Trailers {
-    /// Sometimes the doc comment ends with parentheses (like this)
-    //~^ doc_comments_missing_terminal_punctuation
-    EndsWithParens,
-    /// (Sometimes the last sentence is in parentheses, but there is no special treatment of this.)
-    //~^ doc_comments_missing_terminal_punctuation
-    ParensFailing,
+    /// Sometimes the last sentence ends with parentheses (and that's ok).
+    ParensPassing,
+    /// (Sometimes the last sentence is in parentheses.)
+    SentenceInParensPassing,
     /// **Sometimes the last sentence is in bold, and that's ok.**
     DoubleStarPassing,
     /// **But sometimes it is missing a period**
@@ -97,10 +95,9 @@ enum Trailers {
     //~^ doc_comments_missing_terminal_punctuation
     UnderscoreFailing,
     /// This comment ends with "a quote."
-    QuotePassing,
-    /// This comment ends with "a quote"
-    //~^ doc_comments_missing_terminal_punctuation
-    QuoteFailing,
+    AmericanStyleQuotePassing,
+    /// This comment ends with "a quote".
+    BritishStyleQuotePassing,
 }
 
 /// Doc comments can end with an [inline link](#anchor)
diff --git a/tests/ui/doc/doc_comments_missing_terminal_punctuation.stderr b/tests/ui/doc/doc_comments_missing_terminal_punctuation.stderr
@@ -44,70 +44,52 @@ LL |     //! inner attributes too
    |                             ^ help: end the doc comment with some punctuation: `.`
 
 error: doc comments should end with a terminal punctuation mark
-  --> tests/ui/doc/doc_comments_missing_terminal_punctuation.rs:83:68
-   |
-LL |     /// Sometimes the doc comment ends with parentheses (like this)
-   |                                                                    ^ help: end the doc comment with some punctuation: `.`
-
-error: doc comments should end with a terminal punctuation mark
-  --> tests/ui/doc/doc_comments_missing_terminal_punctuation.rs:86:100
-   |
-LL |     /// (Sometimes the last sentence is in parentheses, but there is no special treatment of this.)
-   |                                                                                                    ^ help: end the doc comment with some punctuation: `.`
-
-error: doc comments should end with a terminal punctuation mark
-  --> tests/ui/doc/doc_comments_missing_terminal_punctuation.rs:91:47
+  --> tests/ui/doc/doc_comments_missing_terminal_punctuation.rs:89:47
    |
 LL |     /// **But sometimes it is missing a period**
    |                                               ^ help: end the doc comment with some punctuation: `.`
 
 error: doc comments should end with a terminal punctuation mark
-  --> tests/ui/doc/doc_comments_missing_terminal_punctuation.rs:96:46
+  --> tests/ui/doc/doc_comments_missing_terminal_punctuation.rs:94:46
    |
 LL |     /// _But sometimes it is missing a period_
    |                                              ^ help: end the doc comment with some punctuation: `.`
 
 error: doc comments should end with a terminal punctuation mark
-  --> tests/ui/doc/doc_comments_missing_terminal_punctuation.rs:101:40
-   |
-LL |     /// This comment ends with "a quote"
-   |                                        ^ help: end the doc comment with some punctuation: `.`
-
-error: doc comments should end with a terminal punctuation mark
-  --> tests/ui/doc/doc_comments_missing_terminal_punctuation.rs:106:56
+  --> tests/ui/doc/doc_comments_missing_terminal_punctuation.rs:103:56
    |
 LL | /// Doc comments can end with an [inline link](#anchor)
    |                                                        ^ help: end the doc comment with some punctuation: `.`
 
 error: doc comments should end with a terminal punctuation mark
-  --> tests/ui/doc/doc_comments_missing_terminal_punctuation.rs:110:65
+  --> tests/ui/doc/doc_comments_missing_terminal_punctuation.rs:107:65
    |
 LL | /// Some doc comments contain [link reference definitions][spec]
    |                                                                 ^ help: end the doc comment with some punctuation: `.`
 
 error: doc comments should end with a terminal punctuation mark
-  --> tests/ui/doc/doc_comments_missing_terminal_punctuation.rs:135:57
+  --> tests/ui/doc/doc_comments_missing_terminal_punctuation.rs:132:57
    |
 LL | /// Doc comments with trailing blank lines are supported
    |                                                         ^ help: end the doc comment with some punctuation: `.`
 
 error: doc comments should end with a terminal punctuation mark
-  --> tests/ui/doc/doc_comments_missing_terminal_punctuation.rs:143:30
+  --> tests/ui/doc/doc_comments_missing_terminal_punctuation.rs:140:30
    |
 LL | /// Only the last sentence is
    |                              ^ help: end the doc comment with some punctuation: `.`
 
 error: doc comments should end with a terminal punctuation mark
-  --> tests/ui/doc/doc_comments_missing_terminal_punctuation.rs:150:33
+  --> tests/ui/doc/doc_comments_missing_terminal_punctuation.rs:147:33
    |
 LL | /// This ends with a code `span`
    |                                 ^ help: end the doc comment with some punctuation: `.`
 
 error: doc comments should end with a terminal punctuation mark
-  --> tests/ui/doc/doc_comments_missing_terminal_punctuation.rs:159:27
+  --> tests/ui/doc/doc_comments_missing_terminal_punctuation.rs:156:27
    |
 LL |  * Block doc comments work
    |                           ^ help: end the doc comment with some punctuation: `.`
 
-error: aborting due to 18 previous errors
+error: aborting due to 15 previous errors
 
diff --git a/tests/ui/doc/doc_comments_missing_terminal_punctuation_unfixable.rs b/tests/ui/doc/doc_comments_missing_terminal_punctuation_unfixable.rs
@@ -0,0 +1,13 @@
+#![feature(custom_inner_attributes)]
+#![rustfmt::skip]
+#![warn(clippy::doc_comments_missing_terminal_punctuation)]
+//@no-rustfix
+
+enum UnfixableTrailers {
+    /// Sometimes the doc comment ends with parentheses (like this)
+    //~^ doc_comments_missing_terminal_punctuation
+    EndsWithParens,
+    /// This comment ends with "a quote"
+    //~^ doc_comments_missing_terminal_punctuation
+    QuoteFailing,
+}
diff --git a/tests/ui/doc/doc_comments_missing_terminal_punctuation_unfixable.stderr b/tests/ui/doc/doc_comments_missing_terminal_punctuation_unfixable.stderr
@@ -0,0 +1,20 @@
+error: doc comments should end with a terminal punctuation mark
+  --> tests/ui/doc/doc_comments_missing_terminal_punctuation_unfixable.rs:7:68
+   |
+LL |     /// Sometimes the doc comment ends with parentheses (like this)
+   |                                                                    ^
+   |
+   = help: end the doc comment with some punctuation
+   = note: `-D clippy::doc-comments-missing-terminal-punctuation` implied by `-D warnings`
+   = help: to override `-D warnings` add `#[allow(clippy::doc_comments_missing_terminal_punctuation)]`
+
+error: doc comments should end with a terminal punctuation mark
+  --> tests/ui/doc/doc_comments_missing_terminal_punctuation_unfixable.rs:10:41
+   |
+LL |     /// This comment ends with "a quote"
+   |                                         ^
+   |
+   = help: end the doc comment with some punctuation
+
+error: aborting due to 2 previous errors
+
