diff --git a/Sources/SwiftFormat/Rules/BeginDocumentationCommentWithOneLineSummary.swift b/Sources/SwiftFormat/Rules/BeginDocumentationCommentWithOneLineSummary.swift index 6caf28ddc..09fdb92ad 100644 --- a/Sources/SwiftFormat/Rules/BeginDocumentationCommentWithOneLineSummary.swift +++ b/Sources/SwiftFormat/Rules/BeginDocumentationCommentWithOneLineSummary.swift @@ -11,6 +11,7 @@ //===----------------------------------------------------------------------===// import Foundation +import Markdown import SwiftSyntax #if os(macOS) @@ -91,14 +92,20 @@ public final class BeginDocumentationCommentWithOneLineSummary: SyntaxLintRule { /// Diagnose documentation comments that don't start with one sentence summary. private func diagnoseDocComments(in decl: DeclSyntax) { + // Extract the summary from a documentation comment, if it exists, and strip + // out any inline code segments (which shouldn't be considered when looking + // for the end of a sentence). + var inlineCodeRemover = InlineCodeRemover() guard let docComment = DocumentationComment(extractedFrom: decl), - let briefSummary = docComment.briefSummary + let briefSummary = docComment.briefSummary, + let noInlineCodeSummary = inlineCodeRemover.visit(briefSummary) as? Paragraph else { return } // For the purposes of checking the sentence structure of the comment, we can operate on the // plain text; we don't need any of the styling. - let trimmedText = briefSummary.plainText.trimmingCharacters(in: .whitespacesAndNewlines) + let trimmedText = noInlineCodeSummary.plainText + .trimmingCharacters(in: .whitespacesAndNewlines) let (commentSentences, trailingText) = sentences(in: trimmedText) if commentSentences.count == 0 { diagnose(.terminateSentenceWithPeriod(trimmedText), on: decl) @@ -231,3 +238,9 @@ extension Finding.Message { "add a blank comment line after this sentence: \"\(text)\"" } } + +struct InlineCodeRemover: MarkupRewriter { + mutating func visitInlineCode(_ inlineCode: InlineCode) -> Markup? { + nil + } +} diff --git a/Tests/SwiftFormatTests/Rules/BeginDocumentationCommentWithOneLineSummaryTests.swift b/Tests/SwiftFormatTests/Rules/BeginDocumentationCommentWithOneLineSummaryTests.swift index a297a1b3a..f8b19daf1 100644 --- a/Tests/SwiftFormatTests/Rules/BeginDocumentationCommentWithOneLineSummaryTests.swift +++ b/Tests/SwiftFormatTests/Rules/BeginDocumentationCommentWithOneLineSummaryTests.swift @@ -31,6 +31,17 @@ final class BeginDocumentationCommentWithOneLineSummaryTests: LintOrFormatRuleTe // ... } + /// Open a scope enclosed by `"typewriter"` double-quotes. + struct BeginTypewriterDoubleQuotes: MDocMacroProtocol {} + + /// Before parsing arguments, capture all inputs that follow the `--` + /// terminator in this argument array. + public static var postTerminator: ArgumentArrayParsingStrategy + + /// The source converter for the text in the current test, which + /// is related to ``thisInvalid(method.Signature:)``. + var converter: SourceLocationConverter! + /// This docline should not succeed. /// There are two sentences without a blank line between them. 1️⃣struct Test {}