Feat: New plugin flag for skipping synthesized symbols

IntegrationTests/Package.swift

@@ -30,6 +30,7 @@ let package = Package(
                 .copy("Fixtures/MixedTargets"),
                 .copy("Fixtures/TargetWithDocCCatalog"),
                 .copy("Fixtures/PackageWithSnippets"),
+                .copy("Fixtures/PackageWithConformanceSymbols"),
                 .copy("Fixtures/LibraryTargetWithExtensionSymbols"),
             ]
         ),

IntegrationTests/Tests/DocCConvertSynthesizedSymbolsTests.swift

@@ -0,0 +1,49 @@
+// This source file is part of the Swift.org open source project
+//
+// Copyright (c) 2022 Apple Inc. and the Swift project authors
+// Licensed under Apache License v2.0 with Runtime Library Exception
+//
+// See https://swift.org/LICENSE.txt for license information
+// See https://swift.org/CONTRIBUTORS.txt for Swift project authors
+
+import XCTest
+
+final class DocCConvertSynthesizedSymbolsTests: ConcurrencyRequiringTestCase {
+    func testGenerateDocumentationWithSkipSynthesizedSymbolsEnabled() throws {
+        let result = try swiftPackage(
+            "generate-documentation", "--experimental-skip-synthesized-symbols",
+            workingDirectory: try setupTemporaryDirectoryForFixture(named: "PackageWithConformanceSymbols")
+        )
+
+        result.assertExitStatusEquals(0)
+        let doccArchiveURL = try XCTUnwrap(result.referencedDocCArchives.first)
+        let dataDirectoryContents = try filesIn(.dataSubdirectory, of: doccArchiveURL)
+        XCTAssertEqual(
+            Set(dataDirectoryContents.map(\.lastTwoPathComponents)),
+            [
+                "documentation/packagewithconformancesymbols.json",
+                "packagewithconformancesymbols/foo.json"
+            ]
+        )
+    }
+
+    func testGenerateDocumentationWithSynthesizedSymbols() throws {
+        let result = try swiftPackage(
+            "generate-documentation",
+            workingDirectory: try setupTemporaryDirectoryForFixture(named: "PackageWithConformanceSymbols")
+        )
+
+        result.assertExitStatusEquals(0)
+        let doccArchiveURL = try XCTUnwrap(result.referencedDocCArchives.first)
+        let dataDirectoryContents = try filesIn(.dataSubdirectory, of: doccArchiveURL)
+        XCTAssertEqual(
+            Set(dataDirectoryContents.map(\.lastTwoPathComponents)),
+            [
+                "documentation/packagewithconformancesymbols.json",
+                "packagewithconformancesymbols/foo.json",
+                "foo/equatable-implementations.json",
+                "foo/!=(_:_:).json"
+            ]
+        )
+    }
+}

IntegrationTests/Tests/Fixtures/PackageWithConformanceSymbols/Package.swift

@@ -0,0 +1,30 @@
+// swift-tools-version: 5.6
+//
+// This source file is part of the Swift.org open source project
+//
+// Copyright (c) 2022 Apple Inc. and the Swift project authors
+// Licensed under Apache License v2.0 with Runtime Library Exception
+//
+// See https://swift.org/LICENSE.txt for license information
+// See https://swift.org/CONTRIBUTORS.txt for Swift project authors
+
+import Foundation
+import PackageDescription
+
+let package = Package(
+    name: "PackageWithConformanceSymbols",
+    targets: [
+        .target(name: "PackageWithConformanceSymbols")
+    ]
+)
+
+// We only expect 'swift-docc-plugin' to be a sibling when this package
+// is running as part of a test.
+//
+// This allows the package to compile outside of tests for easier
+// test development.
+if FileManager.default.fileExists(atPath: "../swift-docc-plugin") {
+    package.dependencies += [
+        .package(path: "../swift-docc-plugin"),
+    ]
+}

IntegrationTests/Tests/Fixtures/PackageWithConformanceSymbols/Sources/PackageWithConformanceSymbols/FooTest.swift

@@ -0,0 +1,10 @@
+// This source file is part of the Swift.org open source project
+//
+// Copyright (c) 2022 Apple Inc. and the Swift project authors
+// Licensed under Apache License v2.0 with Runtime Library Exception
+//
+// See https://swift.org/LICENSE.txt for license information
+// See https://swift.org/CONTRIBUTORS.txt for Swift project authors
+
+public struct Foo: Hashable {
+}

Plugins/SharedPackagePluginExtensions/PackageManager+getSymbolGraphsForDocC.swift

@@ -55,6 +55,8 @@ extension PackageManager {
 #else
                 print("warning: detected '--include-extended-types' option, which is incompatible with your swift version (required: 5.8)")
 #endif
+            case .skipSynthesizedSymbols:
+                symbolGraphOptions.includeSynthesized = false
             default:
                 fatalError("error: unknown PluginFlag (\(customSymbolGraphOption.parsedValues.joined(separator: ", "))) detected in symbol graph generation - please create an issue at https://github.com/apple/swift-docc-plugin")
          }

Sources/SwiftDocCPluginUtilities/HelpInformation.swift

@@ -45,6 +45,7 @@ public enum HelpInformation {
 
         var supportedPluginFlags = [
             PluginFlag.disableIndex,
+            PluginFlag.skipSynthesizedSymbols
         ]
 
         // stops 'not mutated' warning for Swift 5.7 and lower

Sources/SwiftDocCPluginUtilities/ParsedArguments.swift

@@ -182,7 +182,8 @@ public struct ParsedArguments {
 
     private static let argumentsTransformers: [ArgumentsTransforming] = [
         PluginFlag.disableIndex,
-        PluginFlag.extendedTypes
+        PluginFlag.extendedTypes,
+        PluginFlag.skipSynthesizedSymbols
     ]
 }
 
@@ -201,7 +202,8 @@ private extension ParsedArguments {
             switch self {
             case .dumpSymbolGraph:
                 return [
-                    PluginFlag.extendedTypes
+                    PluginFlag.extendedTypes,
+                    PluginFlag.skipSynthesizedSymbols
                 ]
             case .docc:
                 return []

Sources/SwiftDocCPluginUtilities/PluginFlags/SkipSynthesizedSymbolsFlag.swift

@@ -0,0 +1,24 @@
+// This source file is part of the Swift.org open source project
+//
+// Copyright (c) 2022 Apple Inc. and the Swift project authors
+// Licensed under Apache License v2.0 with Runtime Library Exception
+//
+// See https://swift.org/LICENSE.txt for license information
+// See https://swift.org/CONTRIBUTORS.txt for Swift project authors
+
+extension PluginFlag {
+    /// Exclude synthesized symbols from the generated documentation.
+    ///
+    /// `--experimental-skip-synthesized-symbols` produces a DocC archive without compiler synthesized symbols.
+    static let skipSynthesizedSymbols = PluginFlag(
+        parsedValues: [
+            "--experimental-skip-synthesized-symbols"
+        ],
+        abstract: "Exclude synthesized symbols from the generated documentation",
+        description: """
+            Experimental feature that produces a DocC archive without compiler synthesized symbols.
+            """,
+        argumentTransformation: { $0 }
+    )
+
+}

Tests/SwiftDocCPluginUtilitiesTests/HelpInformationTests.swift

@@ -39,7 +39,10 @@ final class HelpInformationTests: XCTestCase {
               --product <product>     Generate documentation for the specified product.
               --disable-indexing, --no-indexing
                                       Disable indexing for the produced DocC archive.
-                    Produces a DocC archive that is best-suited for hosting online but incompatible with Xcode.\(includeExtendedTypesSection)
+                    Produces a DocC archive that is best-suited for hosting online but incompatible with Xcode.
+              --experimental-skip-synthesized-symbols
+                                      Exclude synthesized symbols from the generated documentation
+                    Experimental feature that produces a DocC archive without compiler synthesized symbols.\(includeExtendedTypesSection)
 
             DOCC OPTIONS:
               --platform <platform>   Set the current release version of a platform.
@@ -128,7 +131,10 @@ final class HelpInformationTests: XCTestCase {
               --product <product>     Preview documentation for the specified product.
               --disable-indexing, --no-indexing
                                       Disable indexing for the produced DocC archive.
-                    Produces a DocC archive that is best-suited for hosting online but incompatible with Xcode.\(includeExtendedTypesSection)
+                    Produces a DocC archive that is best-suited for hosting online but incompatible with Xcode.
+              --experimental-skip-synthesized-symbols
+                                      Exclude synthesized symbols from the generated documentation
+                    Experimental feature that produces a DocC archive without compiler synthesized symbols.\(includeExtendedTypesSection)
 
             DOCC OPTIONS:
               --platform <platform>   Set the current release version of a platform.

Tests/SwiftDocCPluginUtilitiesTests/ParsedArgumentsTests.swift

@@ -444,7 +444,7 @@ final class ParsedArgumentsTests: XCTestCase {
     }
 
     func testDocCArgumentsWithDumpSymbolGraphArguments() {
-        let dumpSymbolGraphArguments = ParsedArguments(["--include-extended-types"])
+        let dumpSymbolGraphArguments = ParsedArguments(["--include-extended-types", "--experimental-skip-synthesized-symbols"])
 
         let doccArguments = dumpSymbolGraphArguments.doccArguments(
             action: .convert,
@@ -456,12 +456,13 @@ final class ParsedArgumentsTests: XCTestCase {
         )
 
         XCTAssertFalse(doccArguments.contains("--include-extended-types"))
+        XCTAssertFalse(doccArguments.contains("--experimental-skip-synthesized-symbols"))
     }
 
     func testDumpSymbolGraphArguments() {
-        let dumpSymbolGraphArguments = ParsedArguments(["--include-extended-types"])
+        let dumpSymbolGraphArguments = ParsedArguments(["--include-extended-types", "--experimental-skip-synthesized-symbols"])
 
-        XCTAssertEqual(dumpSymbolGraphArguments.symbolGraphArguments, [.extendedTypes])
+        XCTAssertEqual(dumpSymbolGraphArguments.symbolGraphArguments, [.extendedTypes, .skipSynthesizedSymbols])
     }
 
     func testDumpSymbolGraphArgumentsWithDocCArguments() {

Tests/SwiftDocCPluginUtilitiesTests/PluginFlags/PluginFlagTests.swift

@@ -76,4 +76,34 @@ final class PluginFlagTests: XCTestCase {
             ]
         )
     }
+
+    func testEquatableConformance() {
+        let examplePluginFlag1 = PluginFlag(
+            parsedValues: ["--example1", "--other-example1"],
+            abstract: "",
+            description: "",
+            argumentTransformation: { $0 }
+        )
+        let examplePluginFlag2 = PluginFlag(
+            parsedValues: ["--example2", "--other-example2"],
+            abstract: "",
+            description: "",
+            argumentTransformation: { $0 }
+        )
+        let examplePluginFlag3 = PluginFlag(
+            parsedValues: ["--example1", "--other-example1"],
+            abstract: "abstract",
+            description: "description",
+            argumentTransformation: { $0 }
+        )
+        let examplePluginFlag4 = PluginFlag(
+            parsedValues: ["--example"],
+            abstract: "",
+            description: "",
+            argumentTransformation: { $0 }
+        )
+        XCTAssertNotEqual(examplePluginFlag1, examplePluginFlag2)
+        XCTAssertNotEqual(examplePluginFlag1, examplePluginFlag4)
+        XCTAssertEqual(examplePluginFlag1, examplePluginFlag3)
+    }
 }

Tests/SwiftDocCPluginUtilitiesTests/PluginFlags/SkipSynthesizedSymbolsFlagTests.swift

@@ -0,0 +1,22 @@
+// This source file is part of the Swift.org open source project
+//
+// Copyright (c) 2022 Apple Inc. and the Swift project authors
+// Licensed under Apache License v2.0 with Runtime Library Exception
+//
+// See https://swift.org/LICENSE.txt for license information
+// See https://swift.org/CONTRIBUTORS.txt for Swift project authors
+
+import Foundation
+@testable import SwiftDocCPluginUtilities
+import XCTest
+
+final class SkipSynthesizedSymbolsFlagTests: XCTestCase {
+    func testNotTransformExistingFlagsWhenPresent() {
+        XCTAssertEqual(
+            PluginFlag.skipSynthesizedSymbols.transform(
+                ["--index", "--other-flag"]
+            ),
+            ["--index", "--other-flag"]
+        )
+    }
+}