diff --git a/Package.swift b/Package.swift
index 36e592b..a733512 100644
--- a/Package.swift
+++ b/Package.swift
@@ -42,8 +42,8 @@ let package = Package(
.binaryTarget(
name: "SwiftFormat",
- url: "https://github.com/calda/SwiftFormat/releases/download/0.54-beta-4/SwiftFormat.artifactbundle.zip",
- checksum: "65335d1e059714d570ee6dbe76d3738fbae3a404dafb109371a6a55670b5bcd7"),
+ url: "https://github.com/calda/SwiftFormat/releases/download/0.54-beta-5/SwiftFormat.artifactbundle.zip",
+ checksum: "7447986db45a51164d23672c07f971406a4c0589b0c423fcb85e95ed8f8e7e48"),
.binaryTarget(
name: "SwiftLintBinary",
diff --git a/README.md b/README.md
index 222552c..fc97429 100644
--- a/README.md
+++ b/README.md
@@ -1649,6 +1649,127 @@ _You can enable the following settings in Xcode by running [this script](resourc
+* (link) **Use doc comments (`///`) instead of regular comments (`//`) before declarations within type bodies or at the top level.** [](https://github.com/nicklockwood/SwiftFormat/blob/master/Rules.md#docComments)
+
+
+
+ ```swift
+ // WRONG
+
+ // A planet that exists somewhere in the universe.
+ class Planet {
+ // Data about the composition and density of the planet's atmosphere if present.
+ var atmosphere: Atmosphere?
+
+ // Data about the size, location, and composition of large bodies of water on the planet's surface.
+ var oceans: [Ocean]
+
+ // Terraforms the planet, by adding an atmosphere and ocean that is hospitable for life.
+ func terraform() {
+ // This gas composition has a pretty good track record so far!
+ let composition = AtmosphereComposition(nitrogen: 0.78, oxygen: 0.22)
+
+ // Generate the atmosphere first, then the oceans. Otherwise, the water will just boil off immediately.
+ generateAtmosphere(using: composition)
+ generateOceans()
+ }
+ }
+
+ // RIGHT
+
+ /// A planet that exists somewhere in the universe.
+ class Planet {
+ /// Data about the composition and density of the planet's atmosphere if present.
+ var atmosphere: Atmosphere?
+
+ /// Data about the size, location, and composition of large bodies of water on the planet's surface.
+ var oceans: [Ocean]
+
+ /// Terraforms the planet, by adding an atmosphere and ocean that is hospitable for life.
+ func terraform() {
+ // This gas composition has a pretty good track record so far!
+ let composition = AtmosphereComposition(nitrogen: 0.78, oxygen: 0.22)
+
+ // Generate the atmosphere first, then the oceans. Otherwise, the water will just boil off immediately.
+ generateAtmosphere(using: composition)
+ generateOceans()
+ }
+ }
+
+ // ALSO RIGHT:
+
+ func terraform() {
+ /// This gas composition has a pretty good track record so far!
+ /// - Doc comments are not required before local declarations in function scopes, but are permitted.
+ let composition = AtmosphereComposition(nitrogen: 0.78, oxygen: 0.22)
+
+ /// Generate the `atmosphere` first, **then** the `oceans`. Otherwise, the water will just boil off immediately.
+ /// - Comments not preceeding declarations can use doc comments, and will not be autocorrected into regular comments.
+ /// This can be useful because Xcode applies markdown styling to doc comments but not regular comments.
+ generateAtmosphere(using: composition)
+ generateOceans()
+ }
+ ```
+
+ Regular comments are permitted before declarations in some cases.
+
+ For example, comment directives like `// swiftformat:`, `// swiftlint:`, `// sourcery:`, `// MARK:` and `// TODO:` are typically required to use regular comments and don't work correctly with doc comments:
+
+ ```swift
+ // RIGHT
+
+ // swiftformat:sort
+ enum FeatureFlags {
+ case allowFasterThanLightTravel
+ case disableGravity
+ case enableDarkEnergy
+ case enableDarkMatter
+ }
+
+ // TODO: There are no more production consumers of this legacy model, so we
+ // should detangle the remaining code dependencies and clean it up.
+ struct LegacyGeocentricUniverseModel {
+ ...
+ }
+ ```
+
+ Regular comments are also allowed before a grouped block of delcarations, since it's possible that the comment refers to the block as a whole rather than just the following declaration:
+
+ ```swift
+ // RIGHT
+
+ enum Planet {
+ // The inner planets
+ case mercury
+ case venus
+ case earth
+ case mars
+
+ // The outer planets
+ case jupiter
+ case saturn
+ case uranus
+ case neptune
+ }
+
+ // ALSO RIGHT
+
+ enum Planet {
+ /// The smallest planet
+ case mercury
+ case venus
+ case earth
+ case mars
+ /// The largest planet
+ case jupiter
+ case saturn
+ case uranus
+ case neptune
+ }
+ ```
+
+
+
* (link) Include spaces or newlines before and after comment delimiters (`//`, `///`, `/*`, and `*/`) [](https://github.com/nicklockwood/SwiftFormat/blob/master/Rules.md#spaceAroundComments) [](https://github.com/nicklockwood/SwiftFormat/blob/master/Rules.md#spaceInsideComments)
diff --git a/Sources/AirbnbSwiftFormatTool/airbnb.swiftformat b/Sources/AirbnbSwiftFormatTool/airbnb.swiftformat
index 58b326b..ce2fa62 100644
--- a/Sources/AirbnbSwiftFormatTool/airbnb.swiftformat
+++ b/Sources/AirbnbSwiftFormatTool/airbnb.swiftformat
@@ -38,6 +38,7 @@
--onelineforeach convert #preferForLoop
--shortoptionals always #typeSugar
--semicolons never #semicolons
+--doccomments preserve #docComments
# We recommend a max width of 100 but _strictly enforce_ a max width of 130
--maxwidth 130 # wrap
@@ -84,6 +85,7 @@
--rules spaceAroundParens
--rules enumNamespaces
--rules blockComments
+--rules docComments
--rules spaceAroundComments
--rules spaceInsideComments
--rules blankLinesAtStartOfScope