Skip to content

Commit 9b12589

Browse files
sofiaromoralessofiaromorales
authored
Add experimental flag for skipping synthesized symbols (#28)
Adds support for the generation of DocC archives without synthesized symbols by passing a new, experimental, plugin flag `--experimental-skip-synthesized-symbols`. Enabling this flag does not transform or post-process any of the passed arguments but overrides the default value of `symbolGraphOptions.includeSynthesized` that is provided to SwiftPM to false.
1 parent 6a8f81a commit 9b12589

File tree

12 files changed

+185
-7
lines changed

12 files changed

+185
-7
lines changed

‎IntegrationTests/Package.swift

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,7 @@ let package = Package(
3030
.copy("Fixtures/MixedTargets"),
3131
.copy("Fixtures/TargetWithDocCCatalog"),
3232
.copy("Fixtures/PackageWithSnippets"),
33+
.copy("Fixtures/PackageWithConformanceSymbols"),
3334
.copy("Fixtures/LibraryTargetWithExtensionSymbols"),
3435
]
3536
),

‎IntegrationTests/Tests/DocCConvertSynthesizedSymbolsTests.swift

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
// This source file is part of the Swift.org open source project
2+
//
3+
// Copyright (c) 2022 Apple Inc. and the Swift project authors
4+
// Licensed under Apache License v2.0 with Runtime Library Exception
5+
//
6+
// See https://swift.org/LICENSE.txt for license information
7+
// See https://swift.org/CONTRIBUTORS.txt for Swift project authors
8+
9+
import XCTest
10+
11+
final class DocCConvertSynthesizedSymbolsTests: ConcurrencyRequiringTestCase {
12+
func testGenerateDocumentationWithSkipSynthesizedSymbolsEnabled() throws {
13+
let result = try swiftPackage(
14+
"generate-documentation", "--experimental-skip-synthesized-symbols",
15+
workingDirectory: try setupTemporaryDirectoryForFixture(named: "PackageWithConformanceSymbols")
16+
)
17+
18+
result.assertExitStatusEquals(0)
19+
let doccArchiveURL = try XCTUnwrap(result.referencedDocCArchives.first)
20+
let dataDirectoryContents = try filesIn(.dataSubdirectory, of: doccArchiveURL)
21+
XCTAssertEqual(
22+
Set(dataDirectoryContents.map(\.lastTwoPathComponents)),
23+
[
24+
"documentation/packagewithconformancesymbols.json",
25+
"packagewithconformancesymbols/foo.json"
26+
]
27+
)
28+
}
29+
30+
func testGenerateDocumentationWithSynthesizedSymbols() throws {
31+
let result = try swiftPackage(
32+
"generate-documentation",
33+
workingDirectory: try setupTemporaryDirectoryForFixture(named: "PackageWithConformanceSymbols")
34+
)
35+
36+
result.assertExitStatusEquals(0)
37+
let doccArchiveURL = try XCTUnwrap(result.referencedDocCArchives.first)
38+
let dataDirectoryContents = try filesIn(.dataSubdirectory, of: doccArchiveURL)
39+
XCTAssertEqual(
40+
Set(dataDirectoryContents.map(\.lastTwoPathComponents)),
41+
[
42+
"documentation/packagewithconformancesymbols.json",
43+
"packagewithconformancesymbols/foo.json",
44+
"foo/equatable-implementations.json",
45+
"foo/!=(_:_:).json"
46+
]
47+
)
48+
}
49+
}

‎IntegrationTests/Tests/Fixtures/PackageWithConformanceSymbols/Package.swift

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
// swift-tools-version: 5.6
2+
//
3+
// This source file is part of the Swift.org open source project
4+
//
5+
// Copyright (c) 2022 Apple Inc. and the Swift project authors
6+
// Licensed under Apache License v2.0 with Runtime Library Exception
7+
//
8+
// See https://swift.org/LICENSE.txt for license information
9+
// See https://swift.org/CONTRIBUTORS.txt for Swift project authors
10+
11+
import Foundation
12+
import PackageDescription
13+
14+
let package = Package(
15+
name: "PackageWithConformanceSymbols",
16+
targets: [
17+
.target(name: "PackageWithConformanceSymbols")
18+
]
19+
)
20+
21+
// We only expect 'swift-docc-plugin' to be a sibling when this package
22+
// is running as part of a test.
23+
//
24+
// This allows the package to compile outside of tests for easier
25+
// test development.
26+
if FileManager.default.fileExists(atPath: "../swift-docc-plugin") {
27+
package.dependencies += [
28+
.package(path: "../swift-docc-plugin"),
29+
]
30+
}

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

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
// This source file is part of the Swift.org open source project
2+
//
3+
// Copyright (c) 2022 Apple Inc. and the Swift project authors
4+
// Licensed under Apache License v2.0 with Runtime Library Exception
5+
//
6+
// See https://swift.org/LICENSE.txt for license information
7+
// See https://swift.org/CONTRIBUTORS.txt for Swift project authors
8+
9+
public struct Foo: Hashable {
10+
}

‎Plugins/SharedPackagePluginExtensions/PackageManager+getSymbolGraphsForDocC.swift

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -55,6 +55,8 @@ extension PackageManager {
5555
#else
5656
print("warning: detected '--include-extended-types' option, which is incompatible with your swift version (required: 5.8)")
5757
#endif
58+
case .skipSynthesizedSymbols:
59+
symbolGraphOptions.includeSynthesized = false
5860
default:
5961
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")
6062
}

‎Sources/SwiftDocCPluginUtilities/HelpInformation.swift

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -45,6 +45,7 @@ public enum HelpInformation {
4545

4646
var supportedPluginFlags = [
4747
PluginFlag.disableIndex,
48+
PluginFlag.skipSynthesizedSymbols
4849
]
4950

5051
// stops 'not mutated' warning for Swift 5.7 and lower

‎Sources/SwiftDocCPluginUtilities/ParsedArguments.swift

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -182,7 +182,8 @@ public struct ParsedArguments {
182182

183183
private static let argumentsTransformers: [ArgumentsTransforming] = [
184184
PluginFlag.disableIndex,
185-
PluginFlag.extendedTypes
185+
PluginFlag.extendedTypes,
186+
PluginFlag.skipSynthesizedSymbols
186187
]
187188
}
188189

@@ -201,7 +202,8 @@ private extension ParsedArguments {
201202
switch self {
202203
case .dumpSymbolGraph:
203204
return [
204-
PluginFlag.extendedTypes
205+
PluginFlag.extendedTypes,
206+
PluginFlag.skipSynthesizedSymbols
205207
]
206208
case .docc:
207209
return []

‎Sources/SwiftDocCPluginUtilities/PluginFlags/SkipSynthesizedSymbolsFlag.swift

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
// This source file is part of the Swift.org open source project
2+
//
3+
// Copyright (c) 2022 Apple Inc. and the Swift project authors
4+
// Licensed under Apache License v2.0 with Runtime Library Exception
5+
//
6+
// See https://swift.org/LICENSE.txt for license information
7+
// See https://swift.org/CONTRIBUTORS.txt for Swift project authors
8+
9+
extension PluginFlag {
10+
/// Exclude synthesized symbols from the generated documentation.
11+
///
12+
/// `--experimental-skip-synthesized-symbols` produces a DocC archive without compiler synthesized symbols.
13+
static let skipSynthesizedSymbols = PluginFlag(
14+
parsedValues: [
15+
"--experimental-skip-synthesized-symbols"
16+
],
17+
abstract: "Exclude synthesized symbols from the generated documentation",
18+
description: """
19+
Experimental feature that produces a DocC archive without compiler synthesized symbols.
20+
""",
21+
argumentTransformation: { $0 }
22+
)
23+
24+
}

‎Tests/SwiftDocCPluginUtilitiesTests/HelpInformationTests.swift

Lines changed: 8 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -39,7 +39,10 @@ final class HelpInformationTests: XCTestCase {
3939
--product <product> Generate documentation for the specified product.
4040
--disable-indexing, --no-indexing
4141
Disable indexing for the produced DocC archive.
42-
Produces a DocC archive that is best-suited for hosting online but incompatible with Xcode.\(includeExtendedTypesSection)
42+
Produces a DocC archive that is best-suited for hosting online but incompatible with Xcode.
43+
--experimental-skip-synthesized-symbols
44+
Exclude synthesized symbols from the generated documentation
45+
Experimental feature that produces a DocC archive without compiler synthesized symbols.\(includeExtendedTypesSection)
4346
4447
DOCC OPTIONS:
4548
--platform <platform> Set the current release version of a platform.
@@ -128,7 +131,10 @@ final class HelpInformationTests: XCTestCase {
128131
--product <product> Preview documentation for the specified product.
129132
--disable-indexing, --no-indexing
130133
Disable indexing for the produced DocC archive.
131-
Produces a DocC archive that is best-suited for hosting online but incompatible with Xcode.\(includeExtendedTypesSection)
134+
Produces a DocC archive that is best-suited for hosting online but incompatible with Xcode.
135+
--experimental-skip-synthesized-symbols
136+
Exclude synthesized symbols from the generated documentation
137+
Experimental feature that produces a DocC archive without compiler synthesized symbols.\(includeExtendedTypesSection)
132138
133139
DOCC OPTIONS:
134140
--platform <platform> Set the current release version of a platform.

‎Tests/SwiftDocCPluginUtilitiesTests/ParsedArgumentsTests.swift

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -444,7 +444,7 @@ final class ParsedArgumentsTests: XCTestCase {
444444
}
445445

446446
func testDocCArgumentsWithDumpSymbolGraphArguments() {
447-
let dumpSymbolGraphArguments = ParsedArguments(["--include-extended-types"])
447+
let dumpSymbolGraphArguments = ParsedArguments(["--include-extended-types", "--experimental-skip-synthesized-symbols"])
448448

449449
let doccArguments = dumpSymbolGraphArguments.doccArguments(
450450
action: .convert,
@@ -456,12 +456,13 @@ final class ParsedArgumentsTests: XCTestCase {
456456
)
457457

458458
XCTAssertFalse(doccArguments.contains("--include-extended-types"))
459+
XCTAssertFalse(doccArguments.contains("--experimental-skip-synthesized-symbols"))
459460
}
460461

461462
func testDumpSymbolGraphArguments() {
462-
let dumpSymbolGraphArguments = ParsedArguments(["--include-extended-types"])
463+
let dumpSymbolGraphArguments = ParsedArguments(["--include-extended-types", "--experimental-skip-synthesized-symbols"])
463464

464-
XCTAssertEqual(dumpSymbolGraphArguments.symbolGraphArguments, [.extendedTypes])
465+
XCTAssertEqual(dumpSymbolGraphArguments.symbolGraphArguments, [.extendedTypes, .skipSynthesizedSymbols])
465466
}
466467

467468
func testDumpSymbolGraphArgumentsWithDocCArguments() {

‎Tests/SwiftDocCPluginUtilitiesTests/PluginFlags/PluginFlagTests.swift

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -76,4 +76,34 @@ final class PluginFlagTests: XCTestCase {
7676
]
7777
)
7878
}
79+
80+
func testEquatableConformance() {
81+
let examplePluginFlag1 = PluginFlag(
82+
parsedValues: ["--example1", "--other-example1"],
83+
abstract: "",
84+
description: "",
85+
argumentTransformation: { $0 }
86+
)
87+
let examplePluginFlag2 = PluginFlag(
88+
parsedValues: ["--example2", "--other-example2"],
89+
abstract: "",
90+
description: "",
91+
argumentTransformation: { $0 }
92+
)
93+
let examplePluginFlag3 = PluginFlag(
94+
parsedValues: ["--example1", "--other-example1"],
95+
abstract: "abstract",
96+
description: "description",
97+
argumentTransformation: { $0 }
98+
)
99+
let examplePluginFlag4 = PluginFlag(
100+
parsedValues: ["--example"],
101+
abstract: "",
102+
description: "",
103+
argumentTransformation: { $0 }
104+
)
105+
XCTAssertNotEqual(examplePluginFlag1, examplePluginFlag2)
106+
XCTAssertNotEqual(examplePluginFlag1, examplePluginFlag4)
107+
XCTAssertEqual(examplePluginFlag1, examplePluginFlag3)
108+
}
79109
}

‎Tests/SwiftDocCPluginUtilitiesTests/PluginFlags/SkipSynthesizedSymbolsFlagTests.swift

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
// This source file is part of the Swift.org open source project
2+
//
3+
// Copyright (c) 2022 Apple Inc. and the Swift project authors
4+
// Licensed under Apache License v2.0 with Runtime Library Exception
5+
//
6+
// See https://swift.org/LICENSE.txt for license information
7+
// See https://swift.org/CONTRIBUTORS.txt for Swift project authors
8+
9+
import Foundation
10+
@testable import SwiftDocCPluginUtilities
11+
import XCTest
12+
13+
final class SkipSynthesizedSymbolsFlagTests: XCTestCase {
14+
func testNotTransformExistingFlagsWhenPresent() {
15+
XCTAssertEqual(
16+
PluginFlag.skipSynthesizedSymbols.transform(
17+
["--index", "--other-flag"]
18+
),
19+
["--index", "--other-flag"]
20+
)
21+
}
22+
}

0 commit comments

Comments
 (0)