Add option to exclude examples from the rule documentation (#3834)

The option can be used if an example has mainly been added as another test case, but is not suitable
as a user example. User examples should be easy to understand. They should clearly show where and
why a rule is applied and where not. Complex examples with rarely used language constructs or
pathological use cases which are indeed important to test but not helpful for understanding can be
hidden from the documentation with this option.

Source/SwiftLintFramework/Documentation/RuleDocumentation.swift

@@ -32,13 +32,15 @@ struct RuleDocumentation {
     var fileContents: String {
         let description = ruleType.description
         var content = [h1(description.name), description.description, detailsSummary(ruleType.init())]
-        if description.nonTriggeringExamples.isNotEmpty {
+        let nonTriggeringExamples = description.nonTriggeringExamples.filter { !$0.excludeFromDocumentation }
+        if nonTriggeringExamples.isNotEmpty {
             content += [h2("Non Triggering Examples")]
-            content += description.nonTriggeringExamples.map(formattedCode)
+            content += nonTriggeringExamples.map(formattedCode)
         }
-        if description.triggeringExamples.isNotEmpty {
+        let triggeringExamples = description.triggeringExamples.filter { !$0.excludeFromDocumentation }
+        if triggeringExamples.isNotEmpty {
             content += [h2("Triggering Examples")]
-            content += description.triggeringExamples.map(formattedCode)
+            content += triggeringExamples.map(formattedCode)
         }
         return content.joined(separator: "\n\n")
     }

Source/SwiftLintFramework/Models/Example.swift

@@ -24,6 +24,14 @@ public struct Example {
     public private(set) var file: StaticString
     /// The line in the file where the example was created
     public var line: UInt
+    /// Specifies whether the example should be excluded from the rule documentation.
+    ///
+    /// It can be set to `true` if an example has mainly been added as another test case, but is not suitable
+    /// as a user example. User examples should be easy to understand. They should clearly show where and
+    /// why a rule is applied and where not. Complex examples with rarely used language constructs or
+    /// pathological use cases which are indeed important to test but not helpful for understanding can be
+    /// hidden from the documentation with this option.
+    let excludeFromDocumentation: Bool
 }
 
 public extension Example {
@@ -39,13 +47,14 @@ public extension Example {
     ///   - line:                 The line in the file where the example is located.
     ///                           Defaults to the line where this initializer is called.
     init(_ code: String, configuration: Any? = nil, testMultiByteOffsets: Bool = true, testOnLinux: Bool = true,
-         file: StaticString = #file, line: UInt = #line) {
+         file: StaticString = #file, line: UInt = #line, excludeFromDocumentation: Bool = false) {
         self.code = code
         self.configuration = configuration
         self.testMultiByteOffsets = testMultiByteOffsets
         self.testOnLinux = testOnLinux
         self.file = file
         self.line = line
+        self.excludeFromDocumentation = excludeFromDocumentation
     }
 
     /// Returns the same example, but with the `code` that is passed in