From fa3ae574d0b9c93a1655424bd4381044274c5cb4 Mon Sep 17 00:00:00 2001 From: Cal Stephens Date: Thu, 28 Mar 2024 15:13:30 -0700 Subject: [PATCH 1/2] Add rule to use doc comments before declarations (#262) --- Package.swift | 4 +- README.md | 121 ++++++++++++++++++ .../AirbnbSwiftFormatTool/airbnb.swiftformat | 2 + 3 files changed, 125 insertions(+), 2 deletions(-) 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.** [![SwiftFormat: docComments](https://img.shields.io/badge/SwiftFormat-docComments-7B0051.svg)](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 `*/`) [![SwiftFormat: spaceAroundComments](https://img.shields.io/badge/SwiftFormat-spaceAroundComments-7B0051.svg)](https://github.com/nicklockwood/SwiftFormat/blob/master/Rules.md#spaceAroundComments) [![SwiftFormat: spaceInsideComments](https://img.shields.io/badge/SwiftFormat-spaceInsideComments-7B0051.svg)](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 From 8b2776fe3decb6fd801a0e10924eec990e9b4b57 Mon Sep 17 00:00:00 2001 From: Cal Stephens Date: Fri, 31 May 2024 08:20:00 -0700 Subject: [PATCH 2/2] Remove "Platforms: macOS" supported platforms banner (#271) --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index fc97429..392b406 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # Airbnb Swift Style Guide -[![](https://img.shields.io/endpoint?url=https%3A%2F%2Fswiftpackageindex.com%2Fapi%2Fpackages%2Fairbnb%2Fswift%2Fbadge%3Ftype%3Dswift-versions)](https://swiftpackageindex.com/airbnb/swift) [![](https://img.shields.io/endpoint?url=https%3A%2F%2Fswiftpackageindex.com%2Fapi%2Fpackages%2Fairbnb%2Fswift%2Fbadge%3Ftype%3Dplatforms)](https://swiftpackageindex.com/airbnb/swift) +[![](https://img.shields.io/endpoint?url=https%3A%2F%2Fswiftpackageindex.com%2Fapi%2Fpackages%2Fairbnb%2Fswift%2Fbadge%3Ftype%3Dswift-versions)](https://swiftpackageindex.com/airbnb/swift) ## Goals