Skip to content

Commit 3df47cd

Browse files
committed
Ignore backticks in documentation abstracts
The linguistic tagger doesn't do a great job recognizing backticks as opening vs. closing quotes, so some valid abstracts that contain backticks were being rejected by the `BeginDocumentationCommentWithOneLineSummary` rule. This change removes any backtick- quoted sections from abstracts before processing, since they aren't important to that judgment.
1 parent 5412cab commit 3df47cd

File tree

2 files changed

+14
-2
lines changed

2 files changed

+14
-2
lines changed

Sources/SwiftFormat/Rules/BeginDocumentationCommentWithOneLineSummary.swift

Lines changed: 7 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -97,8 +97,13 @@ public final class BeginDocumentationCommentWithOneLineSummary: SyntaxLintRule {
9797
else { return }
9898

9999
// For the purposes of checking the sentence structure of the comment, we can operate on the
100-
// plain text; we don't need any of the styling.
101-
let trimmedText = briefSummary.plainText.trimmingCharacters(in: .whitespacesAndNewlines)
100+
// plain text; we don't need any of the styling. Additionally, the backticks that are
101+
// frequently used to denote symbol names cause issues with quote identification, and
102+
// aren't necessary for this purpose.
103+
let trimmedText = briefSummary.plainText
104+
.trimmingCharacters(in: .whitespacesAndNewlines)
105+
.replacingOccurrences(of: "``.+?``", with: "ZZZ", options: .regularExpression)
106+
.replacingOccurrences(of: "`.+?`", with: "zzz", options: .regularExpression)
102107
let (commentSentences, trailingText) = sentences(in: trimmedText)
103108
if commentSentences.count == 0 {
104109
diagnose(.terminateSentenceWithPeriod(trimmedText), on: decl)

Tests/SwiftFormatTests/Rules/BeginDocumentationCommentWithOneLineSummaryTests.swift

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,13 @@ final class BeginDocumentationCommentWithOneLineSummaryTests: LintOrFormatRuleTe
3131
// ...
3232
}
3333
34+
/// Open a scope enclosed by `"typewriter"` double-quotes.
35+
struct BeginTypewriterDoubleQuotes: MDocMacroProtocol {}
36+
37+
/// Before parsing arguments, capture all inputs that follow the `--`
38+
/// terminator in this argument array.
39+
public static var postTerminator: ArgumentArrayParsingStrategy
40+
3441
/// This docline should not succeed.
3542
/// There are two sentences without a blank line between them.
3643
1️⃣struct Test {}

0 commit comments

Comments
 (0)