Add rule to use doc comments before declarations (airbnb#262)

Author: calda

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",

README.md

@@ -1649,6 +1649,127 @@ _You can enable the following settings in Xcode by running [this script](resourc
 
   </details>
 
+* <a id='doc-comments-before-declarations'></a>(<a href='#doc-comments-before-declarations'>link</a>) **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)
+
+  <details>
+
+  ```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
+  }
+  ```
+
+  </details>
+
 * <a id='whitespace-around-comment-delimiters'></a>(<a href='#whitespace-around-comment-delimiters'>link</a>) 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)
 
   <details>

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