Add rule to use doc comments before declarations

[calda]

Please react with 👍/👎 below if you agree or disagree with this proposal.

Summary

This PR proposes a new rule to use doc comments (///) instead of regular comments (//) before declarations within type bodies or at the top level.

// 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()
  }
}

Reasoning

This rule was originally proposed in #198 (Sept 2022). We closed that PR following @swiftal64's thoughtful feedback here: #198 (comment).

There are a few changes to this new proposal that resolves the issues @swiftal64 identified with the previous approach.

1. We never autocorrect doc comments into regular comments. We continue to permit using doc comments elsewhere in the code, even if the comment doesn't precede a declaration in a type body or at the top level. This is supported by a new --doccomments preserve option added to SwiftFormat in nicklockwood/SwiftFormat#1638.

   // 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()
   }

2. The autocorrect implementation intelligently handles comment directives like // swiftformat:, // swiftlint:, // sourcery:, // MARK: and // TODO:. These examples are left as regular comments:

   // 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 {
     ...
   }

3. We continue allowing regular comments before a grouped block of declarations, since it's possible that the comment refers to the block as a whole rather than just the following declaration. This was implemented in nicklockwood/SwiftFormat#1638.

   // 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
   }

These changes resolve all of the feedback that we received during the previous proposal review.