Skip to content

Commit bc56fbc

Browse files
d-ronnqvistd-ronnqvist
authored
Improve detection of inherited documentation comments for parameter and return validation (#1130)
* Improve detection of inherited documentation comments for parameter and return validation rdar://134534169 * Use more straight-forward syntax for accumulating module names * Pass value or new parameter in new tests
1 parent 2336b82 commit bc56fbc

File tree

4 files changed

+45
-10
lines changed

4 files changed

+45
-10
lines changed

‎Sources/SwiftDocC/Model/ParametersAndReturnValidator.swift

Lines changed: 9 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -278,13 +278,16 @@ struct ParametersAndReturnValidator {
278278

279279
/// Checks if the symbol's documentation is inherited from another source location.
280280
private func hasInheritedDocumentationComment(symbol: UnifiedSymbolGraph.Symbol) -> Bool {
281-
let symbolLocationURI = symbol.documentedSymbol?.mixins.getValueIfPresent(for: SymbolGraph.Symbol.Location.self)?.uri
282-
for case .sourceCode(let location, _) in docChunkSources {
283-
// Check if the symbol has documentation from another source location
284-
return location?.uri != symbolLocationURI
281+
guard let documentedSymbol = symbol.documentedSymbol else {
282+
// If there's no doc comment, any documentation comes from an extension file and isn't inherited from another symbol.
283+
return false
285284
}
286-
// If the symbol didn't have any in-source documentation, check if there's a extension file override.
287-
return docChunkSources.isEmpty
285+
286+
// A symbol has inherited documentation if the doc comment doesn't come from the current module.
287+
let moduleNames = symbol.modules.values.reduce(into: Set()) { $0.insert($1.name) }
288+
return !moduleNames.contains(where: { moduleName in
289+
documentedSymbol.isDocCommentFromSameModule(symbolModuleName: moduleName) == true
290+
})
288291
}
289292

290293
private typealias Signatures = [DocumentationDataVariantsTrait: SymbolGraph.Symbol.FunctionSignature]

‎Sources/SwiftDocCTestUtilities/SymbolGraphCreation.swift

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -47,6 +47,7 @@ extension XCTestCase {
4747

4848
package func makeLineList(
4949
docComment: String,
50+
moduleName: String?,
5051
startOffset: SymbolGraph.LineList.SourceRange.Position = defaultSymbolPosition,
5152
url: URL = defaultSymbolURL
5253
) -> SymbolGraph.LineList {
@@ -64,7 +65,8 @@ extension XCTestCase {
6465
)
6566
},
6667
// We want to include the file:// scheme here
67-
uri: url.absoluteString
68+
uri: url.absoluteString,
69+
moduleName: moduleName
6870
)
6971
}
7072

@@ -83,6 +85,7 @@ extension XCTestCase {
8385
kind kindID: SymbolGraph.Symbol.KindIdentifier,
8486
pathComponents: [String],
8587
docComment: String? = nil,
88+
moduleName: String? = nil,
8689
accessLevel: SymbolGraph.Symbol.AccessControl = .init(rawValue: "public"), // Defined internally in SwiftDocC
8790
location: (position: SymbolGraph.LineList.SourceRange.Position, url: URL)? = (defaultSymbolPosition, defaultSymbolURL),
8891
signature: SymbolGraph.Symbol.FunctionSignature? = nil,
@@ -109,6 +112,7 @@ extension XCTestCase {
109112
docComment: docComment.map {
110113
makeLineList(
111114
docComment: $0,
115+
moduleName: moduleName,
112116
startOffset: location?.position ?? defaultSymbolPosition,
113117
url: location?.url ?? defaultSymbolURL
114118
)

‎Tests/SwiftDocCTests/Model/ParametersAndReturnValidatorTests.swift

Lines changed: 30 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -132,6 +132,7 @@ class ParametersAndReturnValidatorTests: XCTestCase {
132132
Folder(name: "swift", content: [
133133
JSONFile(name: "ModuleName.symbols.json", content: makeSymbolGraph(
134134
docComment: nil,
135+
docCommentModuleName: "ModuleName",
135136
sourceLanguage: .swift,
136137
parameters: [],
137138
returnValue: .init(kind: .typeIdentifier, spelling: "String", preciseIdentifier: "s:SS")
@@ -144,6 +145,7 @@ class ParametersAndReturnValidatorTests: XCTestCase {
144145
145146
- Returns: \(returnValueDescription)
146147
""",
148+
docCommentModuleName: "ModuleName",
147149
sourceLanguage: .objectiveC,
148150
parameters: [(name: "error", externalName: nil)],
149151
returnValue: .init(kind: .typeIdentifier, spelling: "NSString", preciseIdentifier: "c:objc(cs)NSString")
@@ -468,6 +470,7 @@ class ParametersAndReturnValidatorTests: XCTestCase {
468470
Folder(name: "swift", content: [
469471
JSONFile(name: "ModuleName.symbols.json", content: makeSymbolGraph(
470472
docComment: nil,
473+
docCommentModuleName: "ModuleName",
471474
sourceLanguage: .swift,
472475
parameters: [],
473476
returnValue: .init(kind: .typeIdentifier, spelling: "Void", preciseIdentifier: "s:s4Voida")
@@ -480,6 +483,7 @@ class ParametersAndReturnValidatorTests: XCTestCase {
480483
481484
- Returns: Some return value description.
482485
""",
486+
docCommentModuleName: "ModuleName",
483487
sourceLanguage: .objectiveC,
484488
parameters: [(name: "error", externalName: nil)],
485489
returnValue: .init(kind: .typeIdentifier, spelling: "BOOL", preciseIdentifier: "c:@T@BOOL")
@@ -511,6 +515,7 @@ class ParametersAndReturnValidatorTests: XCTestCase {
511515
JSONFile(name: "Platform1-ModuleName.symbols.json", content: makeSymbolGraph(
512516
platform: .init(operatingSystem: .init(name: "Platform1")),
513517
docComment: nil,
518+
docCommentModuleName: "ModuleName",
514519
sourceLanguage: .objectiveC,
515520
parameters: [(name: "first", externalName: nil)],
516521
returnValue: .init(kind: .typeIdentifier, spelling: "void", preciseIdentifier: "c:v")
@@ -519,6 +524,7 @@ class ParametersAndReturnValidatorTests: XCTestCase {
519524
JSONFile(name: "Platform2-ModuleName.symbols.json", content: makeSymbolGraph(
520525
platform: .init(operatingSystem: .init(name: "Platform2")),
521526
docComment: nil,
527+
docCommentModuleName: "ModuleName",
522528
sourceLanguage: .objectiveC,
523529
parameters: [(name: "first", externalName: nil), (name: "second", externalName: nil)],
524530
returnValue: .init(kind: .typeIdentifier, spelling: "void", preciseIdentifier: "c:v")
@@ -527,6 +533,7 @@ class ParametersAndReturnValidatorTests: XCTestCase {
527533
JSONFile(name: "Platform3-ModuleName.symbols.json", content: makeSymbolGraph(
528534
platform: .init(operatingSystem: .init(name: "Platform3")),
529535
docComment: nil,
536+
docCommentModuleName: "ModuleName",
530537
sourceLanguage: .objectiveC,
531538
parameters: [(name: "first", externalName: nil),],
532539
returnValue: .init(kind: .typeIdentifier, spelling: "BOOL", preciseIdentifier: "c:@T@BOOL")
@@ -566,6 +573,7 @@ class ParametersAndReturnValidatorTests: XCTestCase {
566573
Folder(name: "swift", content: [
567574
JSONFile(name: "ModuleName.symbols.json", content: makeSymbolGraph(
568575
docComment: nil,
576+
docCommentModuleName: "ModuleName",
569577
sourceLanguage: .swift,
570578
parameters: [(name: "error", externalName: nil)],
571579
returnValue: .init(kind: .typeIdentifier, spelling: "Void", preciseIdentifier: "s:s4Voida")
@@ -578,6 +586,7 @@ class ParametersAndReturnValidatorTests: XCTestCase {
578586
579587
- Parameter error: Some parameter description.
580588
""",
589+
docCommentModuleName: "ModuleName",
581590
sourceLanguage: .objectiveC,
582591
parameters: [(name: "error", externalName: nil)],
583592
returnValue: .init(kind: .typeIdentifier, spelling: "void", preciseIdentifier: "c:v")
@@ -725,14 +734,28 @@ class ParametersAndReturnValidatorTests: XCTestCase {
725734
10 + /// - Parameter first: Some parameter description
726735
| ╰─suggestion: Document 'second' parameter
727736
""")
728-
729-
737+
}
738+
739+
func testDoesNotWarnAboutInheritedDocumentation() throws {
740+
let warningOutput = try warningOutputRaisedFrom(
741+
docComment: """
742+
Some function description
743+
744+
- Parameter second: Some parameter description
745+
- Returns: Nothing.
746+
""",
747+
docCommentModuleName: "SomeOtherModule",
748+
parameters: [(name: "first", externalName: "with"), (name: "second", externalName: "and")],
749+
returnValue: .init(kind: .typeIdentifier, spelling: "Void", preciseIdentifier: "s:s4Voida")
750+
)
751+
XCTAssertEqual(warningOutput, "")
730752
}
731753

732754
// MARK: Test helpers
733755

734756
private func warningOutputRaisedFrom(
735757
docComment: String,
758+
docCommentModuleName: String? = "ModuleName",
736759
parameters: [(name: String, externalName: String?)],
737760
returnValue: SymbolGraph.Symbol.DeclarationFragments.Fragment,
738761
file: StaticString = #file,
@@ -749,6 +772,7 @@ class ParametersAndReturnValidatorTests: XCTestCase {
749772
Folder(name: "unit-test.docc", content: [
750773
JSONFile(name: "ModuleName.symbols.json", content: makeSymbolGraph(
751774
docComment: docComment,
775+
docCommentModuleName: docCommentModuleName,
752776
sourceLanguage: .swift,
753777
parameters: parameters,
754778
returnValue: returnValue
@@ -776,6 +800,7 @@ class ParametersAndReturnValidatorTests: XCTestCase {
776800
private func makeSymbolGraph(docComment: String) -> SymbolGraph {
777801
makeSymbolGraph(
778802
docComment: docComment,
803+
docCommentModuleName: "ModuleName",
779804
sourceLanguage: .swift,
780805
parameters: [
781806
("firstParameter", nil),
@@ -790,12 +815,13 @@ class ParametersAndReturnValidatorTests: XCTestCase {
790815
private func makeSymbolGraph(
791816
platform: SymbolGraph.Platform = .init(),
792817
docComment: String?,
818+
docCommentModuleName: String?,
793819
sourceLanguage: SourceLanguage,
794820
parameters: [(name: String, externalName: String?)],
795821
returnValue: SymbolGraph.Symbol.DeclarationFragments.Fragment
796822
) -> SymbolGraph {
797823
return makeSymbolGraph(
798-
moduleName: "ModuleName",
824+
moduleName: "ModuleName", // Don't use `docCommentModuleName` here.
799825
platform: platform,
800826
symbols: [
801827
makeSymbol(
@@ -804,6 +830,7 @@ class ParametersAndReturnValidatorTests: XCTestCase {
804830
kind: .func,
805831
pathComponents: ["functionName(...)"],
806832
docComment: docComment,
833+
moduleName: docCommentModuleName,
807834
location: (start, symbolURL),
808835
signature: .init(
809836
parameters: parameters.map {

‎Tests/SwiftDocCTests/Semantics/SymbolTests.swift

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1368,6 +1368,7 @@ class SymbolTests: XCTestCase {
13681368

13691369
let newDocComment = self.makeLineList(
13701370
docComment: docComment,
1371+
moduleName: nil,
13711372
startOffset: .init(
13721373
line: docCommentLineOffset,
13731374
character: 0

0 commit comments

Comments
 (0)