diff --git a/Documentation/RuleDocumentation.md b/Documentation/RuleDocumentation.md
index 0b626d5cf..e0ebf7b5c 100644
--- a/Documentation/RuleDocumentation.md
+++ b/Documentation/RuleDocumentation.md
@@ -4,7 +4,7 @@
Use the rules below in the `rules` block of your `.swift-format`
configuration file, as described in
-[Configuration](Configuration.md). All of these rules can be
+[Configuration](Documentation/Configuration.md). All of these rules can be
applied in the linter, but only some of them can format your source code
automatically.
@@ -43,6 +43,7 @@ Here's the list of available rules:
- [OrderedImports](#OrderedImports)
- [ReplaceForEachWithForLoop](#ReplaceForEachWithForLoop)
- [ReturnVoidInsteadOfEmptyTuple](#ReturnVoidInsteadOfEmptyTuple)
+- [StandardizeDocumentationComments](#StandardizeDocumentationComments)
- [TypeNamesShouldBeCapitalized](#TypeNamesShouldBeCapitalized)
- [UseEarlyExits](#UseEarlyExits)
- [UseExplicitNilCheckInConditions](#UseExplicitNilCheckInConditions)
@@ -440,6 +441,22 @@ Format: `-> ()` is replaced with `-> Void`
`ReturnVoidInsteadOfEmptyTuple` rule can format your code automatically.
+### StandardizeDocumentationComments
+
+Reformats documentation comments to a standard structure.
+
+Format: Documentation is reflowed in a standard format:
+- All documentation comments are rendered as `///`-prefixed.
+- Documentation comments are re-wrapped to the preferred line length.
+- The order of elements in a documentation comment is standard:
+ - Abstract
+ - Discussion w/ paragraphs, code samples, lists, etc.
+ - Param docs (outlined if > 1)
+ - Return docs
+ - Throw docs
+
+`StandardizeDocumentationComments` rule can format your code automatically.
+
### TypeNamesShouldBeCapitalized
`struct`, `class`, `enum` and `protocol` declarations should have a capitalized name.
diff --git a/Sources/SwiftFormat/Core/DocumentationComment.swift b/Sources/SwiftFormat/Core/DocumentationComment.swift
index d89b4c1c6..3f4204e1a 100644
--- a/Sources/SwiftFormat/Core/DocumentationComment.swift
+++ b/Sources/SwiftFormat/Core/DocumentationComment.swift
@@ -28,9 +28,9 @@ public struct DocumentationComment {
/// The documentation comment of the parameter.
///
- /// Typically, only the `briefSummary` field of this value will be populated. However, for more
- /// complex cases like parameters whose types are functions, the grammar permits full
- /// descriptions including `Parameter(s)`, `Returns`, and `Throws` fields to be present.
+ /// Typically, only the `briefSummary` field of this value will be populated. However,
+ /// parameters can also include a full discussion, although special fields like
+ /// `Parameter(s)`, `Returns`, and `Throws` are not specifically recognized.
public var comment: DocumentationComment
}
@@ -75,6 +75,13 @@ public struct DocumentationComment {
/// `Throws:` prefix removed for convenience.
public var `throws`: Paragraph? = nil
+ /// A collection of _all_ body nodes at the top level of the comment text.
+ ///
+ /// If a brief summary paragraph was extracted from the comment, it will not be present in this
+ /// collection. Any special fields extracted (parameters, returns, and throws) from `bodyNodes`
+ /// will be present in this collection.
+ internal var allBodyNodes: [Markup] = []
+
/// Creates a new `DocumentationComment` with information extracted from the leading trivia of the
/// given syntax node.
///
@@ -88,8 +95,9 @@ public struct DocumentationComment {
}
// Disable smart quotes and dash conversion since we want to preserve the original content of
- // the comments instead of doing documentation generation.
- let doc = Document(parsing: commentInfo.text, options: [.disableSmartOpts])
+ // the comments instead of doing documentation generation. For the same reason, parse
+ // symbol links to preserve the double-backtick delimiters.
+ let doc = Document(parsing: commentInfo.text, options: [.disableSmartOpts, .parseSymbolLinks])
self.init(markup: doc)
}
@@ -106,6 +114,9 @@ public struct DocumentationComment {
remainingChildren = markup.children.dropFirst(0)
}
+ // Capture all the body nodes before filtering out any special fields.
+ allBodyNodes = remainingChildren.map { $0.detachedFromParent }
+
for child in remainingChildren {
if var list = child.detachedFromParent as? UnorderedList {
// An unordered list could be one of the following:
@@ -129,8 +140,11 @@ public struct DocumentationComment {
extractSimpleFields(from: &list)
- // If the list is now empty, don't add it to the body nodes below.
- guard !list.isEmpty else { continue }
+ // Add the list if non-empty, then `continue` so that we don't add the original node.
+ if !list.isEmpty {
+ bodyNodes.append(list)
+ }
+ continue
}
bodyNodes.append(child.detachedFromParent)
@@ -344,3 +358,135 @@ private struct SimpleFieldMarkupRewriter: MarkupRewriter {
return Text(String(nameAndRemainder[1]))
}
}
+
+extension DocumentationComment {
+ /// Returns a trivia collection containing this documentation comment,
+ /// formatted and rewrapped to the given line width.
+ ///
+ /// - Parameters:
+ /// - lineWidth: The expected line width, including leading spaces, the
+ /// triple-slash prefix, and the documentation text.
+ /// - joiningTrivia: The trivia to put between each line of documentation
+ /// text. `joiningTrivia` must include a `.newlines` trivia piece.
+ /// - Returns: A trivia collection that represents this documentation comment
+ /// in standardized form.
+ func renderForSource(lineWidth: Int, joiningTrivia: some Collection<TriviaPiece>) -> Trivia {
+ // The width of the prefix is 4 (`/// `) plus the number of spaces in `joiningTrivia`.
+ let prefixWidth =
+ 4
+ + joiningTrivia.map {
+ if case .spaces(let n) = $0 { return n } else { return 0 }
+ }.reduce(0, +)
+
+ let options = MarkupFormatter.Options(
+ orderedListNumerals: .incrementing(start: 1),
+ preferredLineLimit: .init(maxLength: lineWidth - prefixWidth, breakWith: .softBreak)
+ )
+
+ var strings: [String] = []
+ if let briefSummary {
+ strings.append(
+ contentsOf: briefSummary.formatForSource(options: options)
+ )
+ }
+
+ if !bodyNodes.isEmpty {
+ if !strings.isEmpty { strings.append("") }
+
+ let renderedBody = bodyNodes.map {
+ $0.formatForSource(options: options)
+ }.joined(separator: [""])
+ strings.append(contentsOf: renderedBody)
+ }
+
+ // Empty line between discussion and the params/returns/throws documentation.
+ if !strings.isEmpty && (!parameters.isEmpty || returns != nil || `throws` != nil) {
+ strings.append("")
+ }
+
+ // FIXME: Need to recurse rather than only using the `briefSummary`
+ switch parameters.count {
+ case 0: break
+ case 1:
+ // Output a single parameter item.
+ let list = UnorderedList([parameters[0].listItem(asSingle: true)])
+ strings.append(contentsOf: list.formatForSource(options: options))
+
+ default:
+ // Build the list of parameters.
+ let paramItems = parameters.map { $0.listItem() }
+ let paramList = UnorderedList(paramItems)
+
+ // Create a list with a single item: the label, followed by the list of parameters.
+ let listItem = ListItem(
+ Paragraph(Text("Parameters:")),
+ paramList
+ )
+ strings.append(
+ contentsOf: UnorderedList(listItem).formatForSource(options: options)
+ )
+ }
+
+ if let returns {
+ let returnsWithLabel = returns.prefixed(with: "Returns:")
+ let list = UnorderedList([ListItem(returnsWithLabel)])
+ strings.append(contentsOf: list.formatForSource(options: options))
+ }
+
+ if let `throws` {
+ let throwsWithLabel = `throws`.prefixed(with: "Throws:")
+ let list = UnorderedList([ListItem(throwsWithLabel)])
+ strings.append(contentsOf: list.formatForSource(options: options))
+ }
+
+ // Convert the pieces into trivia, then join them with the provided spacing.
+ let pieces = strings.map {
+ $0.isEmpty
+ ? TriviaPiece.docLineComment("///")
+ : TriviaPiece.docLineComment("/// " + $0)
+ }
+ let spacedPieces: [TriviaPiece] = pieces.reduce(into: []) { result, piece in
+ result.append(piece)
+ result.append(contentsOf: joiningTrivia)
+ }
+
+ return Trivia(pieces: spacedPieces)
+ }
+}
+
+extension Markup {
+ func formatForSource(options: MarkupFormatter.Options) -> [String] {
+ format(options: options)
+ .split(separator: "\n", omittingEmptySubsequences: false)
+ .map { $0.trimmingTrailingWhitespace() }
+ }
+}
+
+extension Paragraph {
+ func prefixed(with str: String) -> Paragraph {
+ struct ParagraphPrefixMarkupRewriter: MarkupRewriter {
+ /// The list item to which the rewriter will be applied.
+ let prefix: String
+
+ mutating func visitText(_ text: Text) -> Markup? {
+ // Only manipulate the first text node (of the first paragraph).
+ guard text.indexInParent == 0 else { return text }
+ return Text(String(prefix + text.string))
+ }
+ }
+
+ var rewriter = ParagraphPrefixMarkupRewriter(prefix: str)
+ return self.accept(&rewriter) as? Paragraph ?? self
+ }
+}
+
+extension DocumentationComment.Parameter {
+ func listItem(asSingle: Bool = false) -> ListItem {
+ let summary = comment.briefSummary ?? Paragraph()
+ let label = asSingle ? "Parameter \(name):" : "\(name):"
+ let summaryWithLabel = summary.prefixed(with: label)
+ return ListItem(
+ [summaryWithLabel] + comment.allBodyNodes.map { $0 as! BlockMarkup }
+ )
+ }
+}
diff --git a/Sources/SwiftFormat/Core/Pipelines+Generated.swift b/Sources/SwiftFormat/Core/Pipelines+Generated.swift
index 8b0906e3e..1e786e760 100644
--- a/Sources/SwiftFormat/Core/Pipelines+Generated.swift
+++ b/Sources/SwiftFormat/Core/Pipelines+Generated.swift
@@ -46,11 +46,13 @@ class LintPipeline: SyntaxVisitor {
override func visit(_ node: ActorDeclSyntax) -> SyntaxVisitorContinueKind {
visitIfEnabled(AllPublicDeclarationsHaveDocumentation.visit, for: node)
+ visitIfEnabled(StandardizeDocumentationComments.visit, for: node)
visitIfEnabled(TypeNamesShouldBeCapitalized.visit, for: node)
return .visitChildren
}
override func visitPost(_ node: ActorDeclSyntax) {
onVisitPost(rule: AllPublicDeclarationsHaveDocumentation.self, for: node)
+ onVisitPost(rule: StandardizeDocumentationComments.self, for: node)
onVisitPost(rule: TypeNamesShouldBeCapitalized.self, for: node)
}
@@ -65,12 +67,14 @@ class LintPipeline: SyntaxVisitor {
override func visit(_ node: AssociatedTypeDeclSyntax) -> SyntaxVisitorContinueKind {
visitIfEnabled(BeginDocumentationCommentWithOneLineSummary.visit, for: node)
visitIfEnabled(NoLeadingUnderscores.visit, for: node)
+ visitIfEnabled(StandardizeDocumentationComments.visit, for: node)
visitIfEnabled(TypeNamesShouldBeCapitalized.visit, for: node)
return .visitChildren
}
override func visitPost(_ node: AssociatedTypeDeclSyntax) {
onVisitPost(rule: BeginDocumentationCommentWithOneLineSummary.self, for: node)
onVisitPost(rule: NoLeadingUnderscores.self, for: node)
+ onVisitPost(rule: StandardizeDocumentationComments.self, for: node)
onVisitPost(rule: TypeNamesShouldBeCapitalized.self, for: node)
}
@@ -87,6 +91,7 @@ class LintPipeline: SyntaxVisitor {
visitIfEnabled(AlwaysUseLowerCamelCase.visit, for: node)
visitIfEnabled(BeginDocumentationCommentWithOneLineSummary.visit, for: node)
visitIfEnabled(NoLeadingUnderscores.visit, for: node)
+ visitIfEnabled(StandardizeDocumentationComments.visit, for: node)
visitIfEnabled(TypeNamesShouldBeCapitalized.visit, for: node)
visitIfEnabled(UseTripleSlashForDocumentationComments.visit, for: node)
return .visitChildren
@@ -96,6 +101,7 @@ class LintPipeline: SyntaxVisitor {
onVisitPost(rule: AlwaysUseLowerCamelCase.self, for: node)
onVisitPost(rule: BeginDocumentationCommentWithOneLineSummary.self, for: node)
onVisitPost(rule: NoLeadingUnderscores.self, for: node)
+ onVisitPost(rule: StandardizeDocumentationComments.self, for: node)
onVisitPost(rule: TypeNamesShouldBeCapitalized.self, for: node)
onVisitPost(rule: UseTripleSlashForDocumentationComments.self, for: node)
}
@@ -174,6 +180,14 @@ class LintPipeline: SyntaxVisitor {
onVisitPost(rule: UseTripleSlashForDocumentationComments.self, for: node)
}
+ override func visit(_ node: EnumCaseDeclSyntax) -> SyntaxVisitorContinueKind {
+ visitIfEnabled(StandardizeDocumentationComments.visit, for: node)
+ return .visitChildren
+ }
+ override func visitPost(_ node: EnumCaseDeclSyntax) {
+ onVisitPost(rule: StandardizeDocumentationComments.self, for: node)
+ }
+
override func visit(_ node: EnumCaseElementSyntax) -> SyntaxVisitorContinueKind {
visitIfEnabled(AlwaysUseLowerCamelCase.visit, for: node)
visitIfEnabled(NoLeadingUnderscores.visit, for: node)
@@ -198,6 +212,7 @@ class LintPipeline: SyntaxVisitor {
visitIfEnabled(FullyIndirectEnum.visit, for: node)
visitIfEnabled(NoLeadingUnderscores.visit, for: node)
visitIfEnabled(OneCasePerLine.visit, for: node)
+ visitIfEnabled(StandardizeDocumentationComments.visit, for: node)
visitIfEnabled(TypeNamesShouldBeCapitalized.visit, for: node)
visitIfEnabled(UseTripleSlashForDocumentationComments.visit, for: node)
return .visitChildren
@@ -208,6 +223,7 @@ class LintPipeline: SyntaxVisitor {
onVisitPost(rule: FullyIndirectEnum.self, for: node)
onVisitPost(rule: NoLeadingUnderscores.self, for: node)
onVisitPost(rule: OneCasePerLine.self, for: node)
+ onVisitPost(rule: StandardizeDocumentationComments.self, for: node)
onVisitPost(rule: TypeNamesShouldBeCapitalized.self, for: node)
onVisitPost(rule: UseTripleSlashForDocumentationComments.self, for: node)
}
@@ -215,12 +231,14 @@ class LintPipeline: SyntaxVisitor {
override func visit(_ node: ExtensionDeclSyntax) -> SyntaxVisitorContinueKind {
visitIfEnabled(AvoidRetroactiveConformances.visit, for: node)
visitIfEnabled(NoAccessLevelOnExtensionDeclaration.visit, for: node)
+ visitIfEnabled(StandardizeDocumentationComments.visit, for: node)
visitIfEnabled(UseTripleSlashForDocumentationComments.visit, for: node)
return .visitChildren
}
override func visitPost(_ node: ExtensionDeclSyntax) {
onVisitPost(rule: AvoidRetroactiveConformances.self, for: node)
onVisitPost(rule: NoAccessLevelOnExtensionDeclaration.self, for: node)
+ onVisitPost(rule: StandardizeDocumentationComments.self, for: node)
onVisitPost(rule: UseTripleSlashForDocumentationComments.self, for: node)
}
@@ -260,6 +278,7 @@ class LintPipeline: SyntaxVisitor {
visitIfEnabled(BeginDocumentationCommentWithOneLineSummary.visit, for: node)
visitIfEnabled(NoLeadingUnderscores.visit, for: node)
visitIfEnabled(OmitExplicitReturns.visit, for: node)
+ visitIfEnabled(StandardizeDocumentationComments.visit, for: node)
visitIfEnabled(UseTripleSlashForDocumentationComments.visit, for: node)
visitIfEnabled(ValidateDocumentationComments.visit, for: node)
return .visitChildren
@@ -270,6 +289,7 @@ class LintPipeline: SyntaxVisitor {
onVisitPost(rule: BeginDocumentationCommentWithOneLineSummary.self, for: node)
onVisitPost(rule: NoLeadingUnderscores.self, for: node)
onVisitPost(rule: OmitExplicitReturns.self, for: node)
+ onVisitPost(rule: StandardizeDocumentationComments.self, for: node)
onVisitPost(rule: UseTripleSlashForDocumentationComments.self, for: node)
onVisitPost(rule: ValidateDocumentationComments.self, for: node)
}
@@ -361,6 +381,7 @@ class LintPipeline: SyntaxVisitor {
override func visit(_ node: InitializerDeclSyntax) -> SyntaxVisitorContinueKind {
visitIfEnabled(AllPublicDeclarationsHaveDocumentation.visit, for: node)
visitIfEnabled(BeginDocumentationCommentWithOneLineSummary.visit, for: node)
+ visitIfEnabled(StandardizeDocumentationComments.visit, for: node)
visitIfEnabled(UseTripleSlashForDocumentationComments.visit, for: node)
visitIfEnabled(ValidateDocumentationComments.visit, for: node)
return .visitChildren
@@ -368,6 +389,7 @@ class LintPipeline: SyntaxVisitor {
override func visitPost(_ node: InitializerDeclSyntax) {
onVisitPost(rule: AllPublicDeclarationsHaveDocumentation.self, for: node)
onVisitPost(rule: BeginDocumentationCommentWithOneLineSummary.self, for: node)
+ onVisitPost(rule: StandardizeDocumentationComments.self, for: node)
onVisitPost(rule: UseTripleSlashForDocumentationComments.self, for: node)
onVisitPost(rule: ValidateDocumentationComments.self, for: node)
}
@@ -380,6 +402,14 @@ class LintPipeline: SyntaxVisitor {
onVisitPost(rule: GroupNumericLiterals.self, for: node)
}
+ override func visit(_ node: MacroDeclSyntax) -> SyntaxVisitorContinueKind {
+ visitIfEnabled(StandardizeDocumentationComments.visit, for: node)
+ return .visitChildren
+ }
+ override func visitPost(_ node: MacroDeclSyntax) {
+ onVisitPost(rule: StandardizeDocumentationComments.self, for: node)
+ }
+
override func visit(_ node: MacroExpansionExprSyntax) -> SyntaxVisitorContinueKind {
visitIfEnabled(NoPlaygroundLiterals.visit, for: node)
return .visitChildren
@@ -414,6 +444,14 @@ class LintPipeline: SyntaxVisitor {
onVisitPost(rule: NoEmptyLinesOpeningClosingBraces.self, for: node)
}
+ override func visit(_ node: OperatorDeclSyntax) -> SyntaxVisitorContinueKind {
+ visitIfEnabled(StandardizeDocumentationComments.visit, for: node)
+ return .visitChildren
+ }
+ override func visitPost(_ node: OperatorDeclSyntax) {
+ onVisitPost(rule: StandardizeDocumentationComments.self, for: node)
+ }
+
override func visit(_ node: OptionalBindingConditionSyntax) -> SyntaxVisitorContinueKind {
visitIfEnabled(AlwaysUseLowerCamelCase.visit, for: node)
return .visitChildren
@@ -448,6 +486,7 @@ class LintPipeline: SyntaxVisitor {
visitIfEnabled(AllPublicDeclarationsHaveDocumentation.visit, for: node)
visitIfEnabled(BeginDocumentationCommentWithOneLineSummary.visit, for: node)
visitIfEnabled(NoLeadingUnderscores.visit, for: node)
+ visitIfEnabled(StandardizeDocumentationComments.visit, for: node)
visitIfEnabled(TypeNamesShouldBeCapitalized.visit, for: node)
visitIfEnabled(UseTripleSlashForDocumentationComments.visit, for: node)
return .visitChildren
@@ -456,6 +495,7 @@ class LintPipeline: SyntaxVisitor {
onVisitPost(rule: AllPublicDeclarationsHaveDocumentation.self, for: node)
onVisitPost(rule: BeginDocumentationCommentWithOneLineSummary.self, for: node)
onVisitPost(rule: NoLeadingUnderscores.self, for: node)
+ onVisitPost(rule: StandardizeDocumentationComments.self, for: node)
onVisitPost(rule: TypeNamesShouldBeCapitalized.self, for: node)
onVisitPost(rule: UseTripleSlashForDocumentationComments.self, for: node)
}
@@ -492,6 +532,7 @@ class LintPipeline: SyntaxVisitor {
visitIfEnabled(AllPublicDeclarationsHaveDocumentation.visit, for: node)
visitIfEnabled(BeginDocumentationCommentWithOneLineSummary.visit, for: node)
visitIfEnabled(NoLeadingUnderscores.visit, for: node)
+ visitIfEnabled(StandardizeDocumentationComments.visit, for: node)
visitIfEnabled(TypeNamesShouldBeCapitalized.visit, for: node)
visitIfEnabled(UseSynthesizedInitializer.visit, for: node)
visitIfEnabled(UseTripleSlashForDocumentationComments.visit, for: node)
@@ -501,6 +542,7 @@ class LintPipeline: SyntaxVisitor {
onVisitPost(rule: AllPublicDeclarationsHaveDocumentation.self, for: node)
onVisitPost(rule: BeginDocumentationCommentWithOneLineSummary.self, for: node)
onVisitPost(rule: NoLeadingUnderscores.self, for: node)
+ onVisitPost(rule: StandardizeDocumentationComments.self, for: node)
onVisitPost(rule: TypeNamesShouldBeCapitalized.self, for: node)
onVisitPost(rule: UseSynthesizedInitializer.self, for: node)
onVisitPost(rule: UseTripleSlashForDocumentationComments.self, for: node)
@@ -510,6 +552,7 @@ class LintPipeline: SyntaxVisitor {
visitIfEnabled(AllPublicDeclarationsHaveDocumentation.visit, for: node)
visitIfEnabled(BeginDocumentationCommentWithOneLineSummary.visit, for: node)
visitIfEnabled(OmitExplicitReturns.visit, for: node)
+ visitIfEnabled(StandardizeDocumentationComments.visit, for: node)
visitIfEnabled(UseTripleSlashForDocumentationComments.visit, for: node)
return .visitChildren
}
@@ -517,6 +560,7 @@ class LintPipeline: SyntaxVisitor {
onVisitPost(rule: AllPublicDeclarationsHaveDocumentation.self, for: node)
onVisitPost(rule: BeginDocumentationCommentWithOneLineSummary.self, for: node)
onVisitPost(rule: OmitExplicitReturns.self, for: node)
+ onVisitPost(rule: StandardizeDocumentationComments.self, for: node)
onVisitPost(rule: UseTripleSlashForDocumentationComments.self, for: node)
}
@@ -574,6 +618,7 @@ class LintPipeline: SyntaxVisitor {
visitIfEnabled(AllPublicDeclarationsHaveDocumentation.visit, for: node)
visitIfEnabled(BeginDocumentationCommentWithOneLineSummary.visit, for: node)
visitIfEnabled(NoLeadingUnderscores.visit, for: node)
+ visitIfEnabled(StandardizeDocumentationComments.visit, for: node)
visitIfEnabled(TypeNamesShouldBeCapitalized.visit, for: node)
visitIfEnabled(UseTripleSlashForDocumentationComments.visit, for: node)
return .visitChildren
@@ -582,6 +627,7 @@ class LintPipeline: SyntaxVisitor {
onVisitPost(rule: AllPublicDeclarationsHaveDocumentation.self, for: node)
onVisitPost(rule: BeginDocumentationCommentWithOneLineSummary.self, for: node)
onVisitPost(rule: NoLeadingUnderscores.self, for: node)
+ onVisitPost(rule: StandardizeDocumentationComments.self, for: node)
onVisitPost(rule: TypeNamesShouldBeCapitalized.self, for: node)
onVisitPost(rule: UseTripleSlashForDocumentationComments.self, for: node)
}
@@ -592,6 +638,7 @@ class LintPipeline: SyntaxVisitor {
visitIfEnabled(BeginDocumentationCommentWithOneLineSummary.visit, for: node)
visitIfEnabled(DontRepeatTypeInStaticProperties.visit, for: node)
visitIfEnabled(NeverUseImplicitlyUnwrappedOptionals.visit, for: node)
+ visitIfEnabled(StandardizeDocumentationComments.visit, for: node)
visitIfEnabled(UseTripleSlashForDocumentationComments.visit, for: node)
return .visitChildren
}
@@ -601,6 +648,7 @@ class LintPipeline: SyntaxVisitor {
onVisitPost(rule: BeginDocumentationCommentWithOneLineSummary.self, for: node)
onVisitPost(rule: DontRepeatTypeInStaticProperties.self, for: node)
onVisitPost(rule: NeverUseImplicitlyUnwrappedOptionals.self, for: node)
+ onVisitPost(rule: StandardizeDocumentationComments.self, for: node)
onVisitPost(rule: UseTripleSlashForDocumentationComments.self, for: node)
}
@@ -635,6 +683,7 @@ extension FormatPipeline {
node = OneVariableDeclarationPerLine(context: context).rewrite(node)
node = OrderedImports(context: context).rewrite(node)
node = ReturnVoidInsteadOfEmptyTuple(context: context).rewrite(node)
+ node = StandardizeDocumentationComments(context: context).rewrite(node)
node = UseEarlyExits(context: context).rewrite(node)
node = UseExplicitNilCheckInConditions(context: context).rewrite(node)
node = UseLetInEveryBoundCaseVariable(context: context).rewrite(node)
diff --git a/Sources/SwiftFormat/Core/RuleNameCache+Generated.swift b/Sources/SwiftFormat/Core/RuleNameCache+Generated.swift
index ed06b5577..b41928783 100644
--- a/Sources/SwiftFormat/Core/RuleNameCache+Generated.swift
+++ b/Sources/SwiftFormat/Core/RuleNameCache+Generated.swift
@@ -48,6 +48,7 @@ public let ruleNameCache: [ObjectIdentifier: String] = [
ObjectIdentifier(OrderedImports.self): "OrderedImports",
ObjectIdentifier(ReplaceForEachWithForLoop.self): "ReplaceForEachWithForLoop",
ObjectIdentifier(ReturnVoidInsteadOfEmptyTuple.self): "ReturnVoidInsteadOfEmptyTuple",
+ ObjectIdentifier(StandardizeDocumentationComments.self): "StandardizeDocumentationComments",
ObjectIdentifier(TypeNamesShouldBeCapitalized.self): "TypeNamesShouldBeCapitalized",
ObjectIdentifier(UseEarlyExits.self): "UseEarlyExits",
ObjectIdentifier(UseExplicitNilCheckInConditions.self): "UseExplicitNilCheckInConditions",
diff --git a/Sources/SwiftFormat/Core/RuleRegistry+Generated.swift b/Sources/SwiftFormat/Core/RuleRegistry+Generated.swift
index d5c9c9ba1..29045408c 100644
--- a/Sources/SwiftFormat/Core/RuleRegistry+Generated.swift
+++ b/Sources/SwiftFormat/Core/RuleRegistry+Generated.swift
@@ -47,6 +47,7 @@
"OrderedImports": true,
"ReplaceForEachWithForLoop": true,
"ReturnVoidInsteadOfEmptyTuple": true,
+ "StandardizeDocumentationComments": false,
"TypeNamesShouldBeCapitalized": true,
"UseEarlyExits": false,
"UseExplicitNilCheckInConditions": true,
diff --git a/Sources/SwiftFormat/Rules/StandardizeDocumentationComments.swift b/Sources/SwiftFormat/Rules/StandardizeDocumentationComments.swift
new file mode 100644
index 000000000..4d79bb8fa
--- /dev/null
+++ b/Sources/SwiftFormat/Rules/StandardizeDocumentationComments.swift
@@ -0,0 +1,195 @@
+//===----------------------------------------------------------------------===//
+//
+// This source file is part of the Swift.org open source project
+//
+// Copyright (c) 2025 Apple Inc. and the Swift project authors
+// Licensed under Apache License v2.0 with Runtime Library Exception
+//
+// See https://swift.org/LICENSE.txt for license information
+// See https://swift.org/CONTRIBUTORS.txt for the list of Swift project authors
+//
+//===----------------------------------------------------------------------===//
+
+import Foundation
+import Markdown
+import SwiftSyntax
+
+/// Reformats documentation comments to a standard structure.
+///
+/// Format: Documentation is reflowed in a standard format:
+/// - All documentation comments are rendered as `///`-prefixed.
+/// - Documentation comments are re-wrapped to the preferred line length.
+/// - The order of elements in a documentation comment is standard:
+/// - Abstract
+/// - Discussion w/ paragraphs, code samples, lists, etc.
+/// - Param docs (outlined if > 1)
+/// - Return docs
+/// - Throw docs
+@_spi(Rules)
+public final class StandardizeDocumentationComments: SyntaxFormatRule {
+ public override class var isOptIn: Bool { return true }
+
+ // For each kind of `DeclSyntax` node that we visit, if we modify the node we
+ // need to continue into that node's children, if any exist. These are
+ // different for different node types (e.g. an accessor has a `body`, while an
+ // actor has a `memberBlock`).
+
+ public override func visit(_ node: ActorDeclSyntax) -> DeclSyntax {
+ if var decl = reformatDocumentation(node) {
+ decl.memberBlock = visit(decl.memberBlock)
+ return DeclSyntax(decl)
+ }
+ return super.visit(node)
+ }
+
+ public override func visit(_ node: AssociatedTypeDeclSyntax) -> DeclSyntax {
+ reformatDocumentation(DeclSyntax(node)) ?? super.visit(node)
+ }
+
+ public override func visit(_ node: ClassDeclSyntax) -> DeclSyntax {
+ if var decl = reformatDocumentation(node) {
+ decl.memberBlock = visit(decl.memberBlock)
+ return DeclSyntax(decl)
+ }
+ return super.visit(node)
+ }
+
+ public override func visit(_ node: EnumCaseDeclSyntax) -> DeclSyntax {
+ reformatDocumentation(DeclSyntax(node)) ?? super.visit(node)
+ }
+
+ public override func visit(_ node: EnumDeclSyntax) -> DeclSyntax {
+ if var decl = reformatDocumentation(node) {
+ decl.memberBlock = visit(decl.memberBlock)
+ return DeclSyntax(decl)
+ }
+ return super.visit(node)
+ }
+
+ public override func visit(_ node: ExtensionDeclSyntax) -> DeclSyntax {
+ if var decl = reformatDocumentation(node) {
+ decl.memberBlock = visit(decl.memberBlock)
+ return DeclSyntax(decl)
+ }
+ return super.visit(node)
+ }
+
+ public override func visit(_ node: FunctionDeclSyntax) -> DeclSyntax {
+ if var decl = reformatDocumentation(node) {
+ decl.body = decl.body.map(visit)
+ return DeclSyntax(decl)
+ }
+ return super.visit(node)
+ }
+
+ public override func visit(_ node: InitializerDeclSyntax) -> DeclSyntax {
+ if var decl = reformatDocumentation(node) {
+ decl.body = decl.body.map(visit)
+ return DeclSyntax(decl)
+ }
+ return super.visit(node)
+ }
+
+ public override func visit(_ node: MacroDeclSyntax) -> DeclSyntax {
+ reformatDocumentation(DeclSyntax(node)) ?? super.visit(node)
+ }
+
+ public override func visit(_ node: OperatorDeclSyntax) -> DeclSyntax {
+ reformatDocumentation(DeclSyntax(node)) ?? super.visit(node)
+ }
+
+ public override func visit(_ node: ProtocolDeclSyntax) -> DeclSyntax {
+ if var decl = reformatDocumentation(node) {
+ decl.memberBlock = visit(decl.memberBlock)
+ return DeclSyntax(decl)
+ }
+ return super.visit(node)
+ }
+
+ public override func visit(_ node: StructDeclSyntax) -> DeclSyntax {
+ if var decl = reformatDocumentation(node) {
+ decl.memberBlock = visit(decl.memberBlock)
+ return DeclSyntax(decl)
+ }
+ return super.visit(node)
+ }
+
+ public override func visit(_ node: SubscriptDeclSyntax) -> DeclSyntax {
+ if var decl = reformatDocumentation(node) {
+ decl.accessorBlock = decl.accessorBlock.map(visit)
+ return DeclSyntax(decl)
+ }
+ return super.visit(node)
+ }
+
+ public override func visit(_ node: TypeAliasDeclSyntax) -> DeclSyntax {
+ reformatDocumentation(DeclSyntax(node)) ?? super.visit(node)
+ }
+
+ public override func visit(_ node: VariableDeclSyntax) -> DeclSyntax {
+ reformatDocumentation(DeclSyntax(node)) ?? super.visit(node)
+ }
+
+ private func reformatDocumentation<T: DeclSyntaxProtocol>(
+ _ node: T
+ ) -> T? {
+ guard let docComment = DocumentationComment(extractedFrom: node)
+ else { return nil }
+
+ // Find the start of the documentation that is attached to this
+ // identifier, skipping over any trivia that doesn't actually
+ // attach (like `//` comments or full blank lines).
+ let docCommentTrivia = Array(node.leadingTrivia)
+ guard let startOfActualDocumentation = findStartOfDocComments(in: docCommentTrivia)
+ else { return node }
+
+ // We need to preserve everything up to `startOfActualDocumentation`.
+ let preDocumentationTrivia = Trivia(pieces: node.leadingTrivia[..<startOfActualDocumentation])
+
+ // Next, find the trivia between the declaration and the last comment.
+ // This is the trivia that we'll need to include between each line of
+ // the documentation comments.
+ guard let startOfLeadingWhitespace = docCommentTrivia.lastIndex(where: \.isDocComment)
+ else { return node }
+ let lineLeadingTrivia = docCommentTrivia[startOfLeadingWhitespace...].dropFirst()
+
+ var result = node
+ result.leadingTrivia =
+ preDocumentationTrivia
+ + docComment.renderForSource(
+ lineWidth: context.configuration.lineLength,
+ joiningTrivia: lineLeadingTrivia
+ )
+ return result
+ }
+}
+
+fileprivate func findStartOfDocComments(in trivia: [TriviaPiece]) -> Int? {
+ let startOfCommentSection =
+ trivia.lastIndex(where: { !$0.continuesDocComment })
+ ?? trivia.startIndex
+ return trivia[startOfCommentSection...].firstIndex(where: \.isDocComment)
+}
+
+extension TriviaPiece {
+ fileprivate var isDocComment: Bool {
+ switch self {
+ case .docBlockComment, .docLineComment: return true
+ default: return false
+ }
+ }
+
+ fileprivate var continuesDocComment: Bool {
+ if isDocComment { return true }
+ switch self {
+ // Any amount of horizontal whitespace is okay
+ case .spaces, .tabs:
+ return true
+ // One line break is okay
+ case .newlines(1), .carriageReturns(1), .carriageReturnLineFeeds(1):
+ return true
+ default:
+ return false
+ }
+ }
+}
diff --git a/Tests/SwiftFormatTests/Rules/StandardizeDocumentationCommentsTests.swift b/Tests/SwiftFormatTests/Rules/StandardizeDocumentationCommentsTests.swift
new file mode 100644
index 000000000..ced7054ca
--- /dev/null
+++ b/Tests/SwiftFormatTests/Rules/StandardizeDocumentationCommentsTests.swift
@@ -0,0 +1,606 @@
+//===----------------------------------------------------------------------===//
+//
+// This source file is part of the Swift.org open source project
+//
+// Copyright (c) 2025 Apple Inc. and the Swift project authors
+// Licensed under Apache License v2.0 with Runtime Library Exception
+//
+// See https://swift.org/LICENSE.txt for license information
+// See https://swift.org/CONTRIBUTORS.txt for the list of Swift project authors
+//
+//===----------------------------------------------------------------------===//
+
+@_spi(Rules) import SwiftFormat
+import _SwiftFormatTestSupport
+
+class StandardizeDocumentationCommentsTests: LintOrFormatRuleTestCase {
+ static var configuration: Configuration {
+ var c = Configuration()
+ c.lineLength = 80
+ return c
+ }
+
+ func testFunction() {
+ assertFormatting(
+ StandardizeDocumentationComments.self,
+ input: """
+ /// Returns a collection of subsequences, each with up to the specified length.
+ ///
+ /// If the number of elements in the
+ /// collection is evenly divided by `count`,
+ /// then every chunk will have a length equal to `count`. Otherwise, every chunk but the last will have a length equal to `count`, with the
+ /// remaining elements in the last chunk.
+ ///
+ /// let numbers = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
+ /// for chunk in numbers.chunks(ofCount: 5) {
+ /// print(chunk)
+ /// }
+ /// // [1, 2, 3, 4, 5]
+ /// // [6, 7, 8, 9, 10]
+ ///
+ /// - Parameter count: The desired size of each chunk.
+ /// - Parameter maxChunks: The total number of chunks that may not be exceeded, no matter how many would otherwise be produced.
+ /// - Returns: A collection of consescutive, non-overlapping subseqeunces of
+ /// this collection, where each subsequence (except possibly the last) has
+ /// the length `count`.
+ ///
+ /// - Complexity: O(1) if the collection conforms to `RandomAccessCollection`;
+ /// otherwise, O(*k*), where *k* is equal to `count`.
+ ///
+ public func chunks(ofCount count: Int, maxChunks: Int) -> [[SubSequence]] {}
+ """,
+ expected: """
+ /// Returns a collection of subsequences, each with up to the specified length.
+ ///
+ /// If the number of elements in the collection is evenly divided by `count`,
+ /// then every chunk will have a length equal to `count`. Otherwise, every
+ /// chunk but the last will have a length equal to `count`, with the remaining
+ /// elements in the last chunk.
+ ///
+ /// ```
+ /// let numbers = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
+ /// for chunk in numbers.chunks(ofCount: 5) {
+ /// print(chunk)
+ /// }
+ /// // [1, 2, 3, 4, 5]
+ /// // [6, 7, 8, 9, 10]
+ /// ```
+ ///
+ /// - Complexity: O(1) if the collection conforms to `RandomAccessCollection`;
+ /// otherwise, O(*k*), where *k* is equal to `count`.
+ ///
+ /// - Parameters:
+ /// - count: The desired size of each chunk.
+ /// - maxChunks: The total number of chunks that may not be exceeded, no
+ /// matter how many would otherwise be produced.
+ /// - Returns: A collection of consescutive, non-overlapping subseqeunces of
+ /// this collection, where each subsequence (except possibly the last) has
+ /// the length `count`.
+ public func chunks(ofCount count: Int, maxChunks: Int) -> [[SubSequence]] {}
+ """,
+ findings: [],
+ configuration: Self.configuration
+ )
+ }
+
+ func testNestedFunction() {
+ assertFormatting(
+ StandardizeDocumentationComments.self,
+ input: """
+ // This comment helps verify that leading non-documentation trivia is preserved without changes.
+
+ /// Provides a `chunks(ofCount:)` method, with some more information that should wrap.
+ extension Sequence {
+ /// Returns a collection of subsequences, each with up to the specified length.
+ ///
+ ///
+ /// - Parameter count: The desired size of each chunk.
+ /// - Returns: A collection of consescutive, non-overlapping subseqeunces of
+ /// this collection.
+ ///
+ public func chunks(ofCount count: Int) -> [[SubSequence]] {}
+ }
+ """,
+ expected: """
+ // This comment helps verify that leading non-documentation trivia is preserved without changes.
+
+ /// Provides a `chunks(ofCount:)` method, with some more information that
+ /// should wrap.
+ extension Sequence {
+ /// Returns a collection of subsequences, each with up to the specified
+ /// length.
+ ///
+ /// - Parameter count: The desired size of each chunk.
+ /// - Returns: A collection of consescutive, non-overlapping subseqeunces
+ /// of this collection.
+ public func chunks(ofCount count: Int) -> [[SubSequence]] {}
+ }
+ """,
+ findings: [],
+ configuration: Self.configuration
+ )
+ }
+
+ func testBlockDocumentation() {
+ assertFormatting(
+ StandardizeDocumentationComments.self,
+ input: """
+ /** Provides an initializer that isn't actually possible to implement for all sequences. */
+ extension Sequence {
+ /**
+ Creates a new sequence with the given element repeated the specified number of times.
+ - Parameter element: The element to repeat.
+ - Parameter count: The number of times to repeat `element`. `count` must be greater than or equal to zero.
+ - Complexity: O(1)
+ */
+ public init(repeating element: Element, count: Int) {}
+ }
+ """,
+ expected: """
+ /// Provides an initializer that isn't actually possible to implement for all
+ /// sequences.
+ extension Sequence {
+ /// Creates a new sequence with the given element repeated the specified
+ /// number of times.
+ ///
+ /// - Complexity: O(1)
+ ///
+ /// - Parameters:
+ /// - element: The element to repeat.
+ /// - count: The number of times to repeat `element`. `count` must be
+ /// greater than or equal to zero.
+ public init(repeating element: Element, count: Int) {}
+ }
+ """,
+ findings: [],
+ configuration: Self.configuration
+ )
+ }
+
+ func testDetailedParameters() {
+ assertFormatting(
+ StandardizeDocumentationComments.self,
+ input: """
+ /// Creates an array with the specified capacity, then calls the given
+ /// closure with a buffer covering the array's uninitialized memory.
+ ///
+ /// Inside the closure, set the `initializedCount` parameter to the number of
+ /// elements that are initialized by the closure. The memory in the range
+ /// 'buffer[0..<initializedCount]' must be initialized at the end of the
+ /// closure's execution, and the memory in the range
+ /// 'buffer[initializedCount...]' must be uninitialized. This postcondition
+ /// must hold even if the `initializer` closure throws an error.
+ ///
+ /// - Note: While the resulting array may have a capacity larger than the
+ /// requested amount, the buffer passed to the closure will cover exactly
+ /// the requested number of elements.
+ ///
+ /// - Parameters:
+ /// - unsafeUninitializedCapacity: The number of elements to allocate
+ /// space for in the new array.
+ /// - initializer: A closure that initializes elements and sets the count
+ /// of the new array.
+ /// - Parameters:
+ /// - buffer: A buffer covering uninitialized memory with room for the
+ /// specified number of elements.
+ /// - initializedCount: The count of initialized elements in the array,
+ /// which begins as zero. Set `initializedCount` to the number of
+ /// elements you initialize.
+ @_alwaysEmitIntoClient @inlinable
+ public init(
+ unsafeUninitializedCapacity: Int,
+ initializingWith initializer: (
+ _ buffer: inout UnsafeMutableBufferPointer<Element>,
+ _ initializedCount: inout Int) throws -> Void
+ ) rethrows {}
+ """,
+ expected: """
+ /// Creates an array with the specified capacity, then calls the given closure
+ /// with a buffer covering the array's uninitialized memory.
+ ///
+ /// Inside the closure, set the `initializedCount` parameter to the number of
+ /// elements that are initialized by the closure. The memory in the range
+ /// 'buffer[0..<initializedCount]' must be initialized at the end of the
+ /// closure's execution, and the memory in the range
+ /// 'buffer[initializedCount...]' must be uninitialized. This postcondition
+ /// must hold even if the `initializer` closure throws an error.
+ ///
+ /// - Note: While the resulting array may have a capacity larger than the
+ /// requested amount, the buffer passed to the closure will cover exactly the
+ /// requested number of elements.
+ ///
+ /// - Parameters:
+ /// - unsafeUninitializedCapacity: The number of elements to allocate space
+ /// for in the new array.
+ /// - initializer: A closure that initializes elements and sets the count of
+ /// the new array.
+ /// - Parameters:
+ /// - buffer: A buffer covering uninitialized memory with room for the
+ /// specified number of elements.
+ /// - initializedCount: The count of initialized elements in the array,
+ /// which begins as zero. Set `initializedCount` to the number of
+ /// elements you initialize.
+ @_alwaysEmitIntoClient @inlinable
+ public init(
+ unsafeUninitializedCapacity: Int,
+ initializingWith initializer: (
+ _ buffer: inout UnsafeMutableBufferPointer<Element>,
+ _ initializedCount: inout Int) throws -> Void
+ ) rethrows {}
+ """,
+ findings: [],
+ configuration: Self.configuration
+ )
+ }
+
+ // MARK: Nominal decl tests
+
+ func testActorDecl() {
+ assertFormatting(
+ StandardizeDocumentationComments.self,
+ input: """
+ /// An actor declaration
+ /// with documentation
+ /// that needs to be
+ /// rewrapped to
+ /// the correct width.
+ package actor MyActor {}
+ """,
+ expected: """
+ /// An actor declaration with documentation that needs to be rewrapped to the
+ /// correct width.
+ package actor MyActor {}
+ """,
+ findings: [],
+ configuration: Self.configuration
+ )
+ }
+
+ func testAssociatedTypeDecl() {
+ assertFormatting(
+ StandardizeDocumentationComments.self,
+ input: """
+ /// An associated type declaration
+ /// with documentation
+ /// that needs to be
+ /// rewrapped to
+ /// the correct width.
+ associatedtype MyAssociatedType = Int
+ """,
+ expected: """
+ /// An associated type declaration with documentation that needs to be
+ /// rewrapped to the correct width.
+ associatedtype MyAssociatedType = Int
+ """,
+ findings: [],
+ configuration: Self.configuration
+ )
+ }
+
+ func testClassDecl() {
+ assertFormatting(
+ StandardizeDocumentationComments.self,
+ input: """
+ /// A class declaration
+ /// with documentation
+ /// that needs to be
+ /// rewrapped to
+ /// the correct width.
+ public class MyClass {}
+ """,
+ expected: """
+ /// A class declaration with documentation that needs to be rewrapped to the
+ /// correct width.
+ public class MyClass {}
+ """,
+ findings: [],
+ configuration: Self.configuration
+ )
+ }
+
+ func testEnumAndEnumCaseDecl() {
+ assertFormatting(
+ StandardizeDocumentationComments.self,
+ input: """
+ /// An enum declaration
+ /// with documentation
+ /// that needs to be
+ /// rewrapped to
+ /// the correct width.
+ public enum MyEnum {
+ /// An enum case declaration
+ /// with documentation
+ /// that needs to be
+ /// rewrapped to
+ /// the correct width.
+ case myCase
+ }
+ """,
+ expected: """
+ /// An enum declaration with documentation that needs to be rewrapped to the
+ /// correct width.
+ public enum MyEnum {
+ /// An enum case declaration with documentation that needs to be rewrapped to
+ /// the correct width.
+ case myCase
+ }
+ """,
+ findings: [],
+ configuration: Self.configuration
+ )
+ }
+
+ func testExtensionDecl() {
+ assertFormatting(
+ StandardizeDocumentationComments.self,
+ input: """
+ /// An extension
+ /// with documentation
+ /// that needs to be
+ /// rewrapped to
+ /// the correct width.
+ extension MyClass {}
+ """,
+ expected: """
+ /// An extension with documentation that needs to be rewrapped to the correct
+ /// width.
+ extension MyClass {}
+ """,
+ findings: [],
+ configuration: Self.configuration
+ )
+ }
+
+ func testFunctionDecl() {
+ assertFormatting(
+ StandardizeDocumentationComments.self,
+ input: """
+ /// A function declaration
+ /// with documentation
+ /// that needs to be
+ /// rewrapped to
+ /// the correct width.
+ ///
+ /// - Returns: A value.
+ /// - Throws: An error.
+ ///
+ /// - Parameters:
+ /// - param: A single parameter.
+ /// - Parameter another: A second single parameter.
+ func myFunction(param: String, and another: Int) -> Value {}
+ """,
+ expected: """
+ /// A function declaration with documentation that needs to be rewrapped to the
+ /// correct width.
+ ///
+ /// - Parameters:
+ /// - param: A single parameter.
+ /// - another: A second single parameter.
+ /// - Returns: A value.
+ /// - Throws: An error.
+ func myFunction(param: String, and another: Int) -> Value {}
+ """,
+ findings: [],
+ configuration: Self.configuration
+ )
+ }
+
+ func testInitializerDecl() {
+ assertFormatting(
+ StandardizeDocumentationComments.self,
+ input: """
+ /// An initializer declaration
+ /// with documentation
+ /// that needs to be
+ /// rewrapped to
+ /// the correct width.
+ ///
+ /// - Throws: An error.
+ ///
+ /// - Parameters:
+ /// - param: A single parameter.
+ /// - Parameter another: A second single parameter.
+ public init(param: String, and another: Int) {}
+ """,
+ expected: """
+ /// An initializer declaration with documentation that needs to be rewrapped to
+ /// the correct width.
+ ///
+ /// - Parameters:
+ /// - param: A single parameter.
+ /// - another: A second single parameter.
+ /// - Throws: An error.
+ public init(param: String, and another: Int) {}
+ """,
+ findings: [],
+ configuration: Self.configuration
+ )
+ }
+
+ func testMacroDecl() {
+ assertFormatting(
+ StandardizeDocumentationComments.self,
+ input: """
+ /// A macro declaration
+ /// with documentation
+ /// that needs to be
+ /// rewrapped to
+ /// the correct width.
+ ///
+ /// - Throws: An error.
+ ///
+ /// - Parameters:
+ /// - param: A single parameter.
+ /// - Parameter another: A second single parameter.
+ @freestanding(expression)
+ public macro prohibitBinaryOperators<T>(_ param: T, another: [String]) -> T =
+ #externalMacro(module: "ExampleMacros", type: "ProhibitBinaryOperators")
+ """,
+ expected: """
+ /// A macro declaration with documentation that needs to be rewrapped to the
+ /// correct width.
+ ///
+ /// - Parameters:
+ /// - param: A single parameter.
+ /// - another: A second single parameter.
+ /// - Throws: An error.
+ @freestanding(expression)
+ public macro prohibitBinaryOperators<T>(_ param: T, another: [String]) -> T =
+ #externalMacro(module: "ExampleMacros", type: "ProhibitBinaryOperators")
+ """,
+ findings: [],
+ configuration: Self.configuration
+ )
+ }
+
+ func testOperatorDecl() {
+ assertFormatting(
+ StandardizeDocumentationComments.self,
+ input: """
+ extension Int {
+ /// An operator declaration
+ /// with documentation
+ /// that needs to be
+ /// rewrapped to
+ /// the correct width.
+ ///
+ /// - Parameters:
+ /// - lhs: A single parameter.
+ /// - Parameter rhs: A second single parameter.
+ static func -+-(lhs: Int, rhs: Int) -> Int {}
+ }
+ """,
+ expected: """
+ extension Int {
+ /// An operator declaration with documentation that needs to be rewrapped to
+ /// the correct width.
+ ///
+ /// - Parameters:
+ /// - lhs: A single parameter.
+ /// - rhs: A second single parameter.
+ static func -+-(lhs: Int, rhs: Int) -> Int {}
+ }
+ """,
+ findings: [],
+ configuration: Self.configuration
+ )
+ }
+
+ func testProtocolDecl() {
+ assertFormatting(
+ StandardizeDocumentationComments.self,
+ input: """
+ /// A protocol declaration
+ /// with documentation
+ /// that needs to be
+ /// rewrapped to
+ /// the correct width.
+ protocol MyProto {}
+ """,
+ expected: """
+ /// A protocol declaration with documentation that needs to be rewrapped to the
+ /// correct width.
+ protocol MyProto {}
+ """,
+ findings: [],
+ configuration: Self.configuration
+ )
+ }
+
+ func testStructDecl() {
+ assertFormatting(
+ StandardizeDocumentationComments.self,
+ input: """
+ /// A struct declaration
+ /// with documentation
+ /// that needs to be
+ /// rewrapped to
+ /// the correct width.
+ struct MyStruct {}
+ """,
+ expected: """
+ /// A struct declaration with documentation that needs to be rewrapped to the
+ /// correct width.
+ struct MyStruct {}
+ """,
+ findings: [],
+ configuration: Self.configuration
+ )
+ }
+
+ func testSubscriptDecl() {
+ assertFormatting(
+ StandardizeDocumentationComments.self,
+ input: """
+ /// A subscript declaration
+ /// with documentation
+ /// that needs to be
+ /// rewrapped to
+ /// the correct width.
+ ///
+ /// - Returns: A value.
+ /// - Throws: An error.
+ ///
+ /// - Parameters:
+ /// - param: A single parameter.
+ /// - Parameter another: A second single parameter.
+ public subscript(param: String, and another: Int) -> Value {}
+ """,
+ expected: """
+ /// A subscript declaration with documentation that needs to be rewrapped to
+ /// the correct width.
+ ///
+ /// - Parameters:
+ /// - param: A single parameter.
+ /// - another: A second single parameter.
+ /// - Returns: A value.
+ /// - Throws: An error.
+ public subscript(param: String, and another: Int) -> Value {}
+ """,
+ findings: [],
+ configuration: Self.configuration
+ )
+ }
+
+ func testTypeAliasDecl() {
+ assertFormatting(
+ StandardizeDocumentationComments.self,
+ input: """
+ /// A type alias declaration
+ /// with documentation
+ /// that needs to be
+ /// rewrapped to
+ /// the correct width.
+ typealias MyAlias {}
+ """,
+ expected: """
+ /// A type alias declaration with documentation that needs to be rewrapped to
+ /// the correct width.
+ typealias MyAlias {}
+ """,
+ findings: [],
+ configuration: Self.configuration
+ )
+ }
+
+ func testVariableDecl() {
+ assertFormatting(
+ StandardizeDocumentationComments.self,
+ input: """
+ /// A variable declaration
+ /// with documentation
+ /// that needs to be
+ /// rewrapped to
+ /// the correct width.
+ var myVariable: Int = 5
+ """,
+ expected: """
+ /// A variable declaration with documentation that needs to be rewrapped to the
+ /// correct width.
+ var myVariable: Int = 5
+ """,
+ findings: [],
+ configuration: Self.configuration
+ )
+ }
+}