Skip to content

Commit eaa1e4a

Browse files
d-ronnqvistd-ronnqvist
authored
Improve detection of inherited documentation comments for parameter and return validation (#1130) (#1133)
* 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 c750961 commit eaa1e4a

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")
@@ -476,6 +478,7 @@ class ParametersAndReturnValidatorTests: XCTestCase {
476478
Folder(name: "swift", content: [
477479
JSONFile(name: "ModuleName.symbols.json", content: makeSymbolGraph(
478480
docComment: nil,
481+
docCommentModuleName: "ModuleName",
479482
sourceLanguage: .swift,
480483
parameters: [],
481484
returnValue: .init(kind: .typeIdentifier, spelling: "Void", preciseIdentifier: "s:s4Voida")
@@ -488,6 +491,7 @@ class ParametersAndReturnValidatorTests: XCTestCase {
488491
489492
- Returns: Some return value description.
490493
""",
494+
docCommentModuleName: "ModuleName",
491495
sourceLanguage: .objectiveC,
492496
parameters: [(name: "error", externalName: nil)],
493497
returnValue: .init(kind: .typeIdentifier, spelling: "BOOL", preciseIdentifier: "c:@T@BOOL")
@@ -520,6 +524,7 @@ class ParametersAndReturnValidatorTests: XCTestCase {
520524
JSONFile(name: "Platform1-ModuleName.symbols.json", content: makeSymbolGraph(
521525
platform: .init(operatingSystem: .init(name: "Platform1")),
522526
docComment: nil,
527+
docCommentModuleName: "ModuleName",
523528
sourceLanguage: .objectiveC,
524529
parameters: [(name: "first", externalName: nil)],
525530
returnValue: .init(kind: .typeIdentifier, spelling: "void", preciseIdentifier: "c:v")
@@ -528,6 +533,7 @@ class ParametersAndReturnValidatorTests: XCTestCase {
528533
JSONFile(name: "Platform2-ModuleName.symbols.json", content: makeSymbolGraph(
529534
platform: .init(operatingSystem: .init(name: "Platform2")),
530535
docComment: nil,
536+
docCommentModuleName: "ModuleName",
531537
sourceLanguage: .objectiveC,
532538
parameters: [(name: "first", externalName: nil), (name: "second", externalName: nil)],
533539
returnValue: .init(kind: .typeIdentifier, spelling: "void", preciseIdentifier: "c:v")
@@ -536,6 +542,7 @@ class ParametersAndReturnValidatorTests: XCTestCase {
536542
JSONFile(name: "Platform3-ModuleName.symbols.json", content: makeSymbolGraph(
537543
platform: .init(operatingSystem: .init(name: "Platform3")),
538544
docComment: nil,
545+
docCommentModuleName: "ModuleName",
539546
sourceLanguage: .objectiveC,
540547
parameters: [(name: "first", externalName: nil),],
541548
returnValue: .init(kind: .typeIdentifier, spelling: "BOOL", preciseIdentifier: "c:@T@BOOL")
@@ -575,6 +582,7 @@ class ParametersAndReturnValidatorTests: XCTestCase {
575582
Folder(name: "swift", content: [
576583
JSONFile(name: "ModuleName.symbols.json", content: makeSymbolGraph(
577584
docComment: nil,
585+
docCommentModuleName: "ModuleName",
578586
sourceLanguage: .swift,
579587
parameters: [(name: "error", externalName: nil)],
580588
returnValue: .init(kind: .typeIdentifier, spelling: "Void", preciseIdentifier: "s:s4Voida")
@@ -587,6 +595,7 @@ class ParametersAndReturnValidatorTests: XCTestCase {
587595
588596
- Parameter error: Some parameter description.
589597
""",
598+
docCommentModuleName: "ModuleName",
590599
sourceLanguage: .objectiveC,
591600
parameters: [(name: "error", externalName: nil)],
592601
returnValue: .init(kind: .typeIdentifier, spelling: "void", preciseIdentifier: "c:v")
@@ -734,14 +743,28 @@ class ParametersAndReturnValidatorTests: XCTestCase {
734743
10 + /// - Parameter first: Some parameter description
735744
| ╰─suggestion: Document 'second' parameter
736745
""")
737-
738-
746+
}
747+
748+
func testDoesNotWarnAboutInheritedDocumentation() throws {
749+
let warningOutput = try warningOutputRaisedFrom(
750+
docComment: """
751+
Some function description
752+
753+
- Parameter second: Some parameter description
754+
- Returns: Nothing.
755+
""",
756+
docCommentModuleName: "SomeOtherModule",
757+
parameters: [(name: "first", externalName: "with"), (name: "second", externalName: "and")],
758+
returnValue: .init(kind: .typeIdentifier, spelling: "Void", preciseIdentifier: "s:s4Voida")
759+
)
760+
XCTAssertEqual(warningOutput, "")
739761
}
740762

741763
// MARK: Test helpers
742764

743765
private func warningOutputRaisedFrom(
744766
docComment: String,
767+
docCommentModuleName: String? = "ModuleName",
745768
parameters: [(name: String, externalName: String?)],
746769
returnValue: SymbolGraph.Symbol.DeclarationFragments.Fragment,
747770
file: StaticString = #file,
@@ -758,6 +781,7 @@ class ParametersAndReturnValidatorTests: XCTestCase {
758781
Folder(name: "unit-test.docc", content: [
759782
JSONFile(name: "ModuleName.symbols.json", content: makeSymbolGraph(
760783
docComment: docComment,
784+
docCommentModuleName: docCommentModuleName,
761785
sourceLanguage: .swift,
762786
parameters: parameters,
763787
returnValue: returnValue
@@ -785,6 +809,7 @@ class ParametersAndReturnValidatorTests: XCTestCase {
785809
private func makeSymbolGraph(docComment: String) -> SymbolGraph {
786810
makeSymbolGraph(
787811
docComment: docComment,
812+
docCommentModuleName: "ModuleName",
788813
sourceLanguage: .swift,
789814
parameters: [
790815
("firstParameter", nil),
@@ -799,12 +824,13 @@ class ParametersAndReturnValidatorTests: XCTestCase {
799824
private func makeSymbolGraph(
800825
platform: SymbolGraph.Platform = .init(),
801826
docComment: String?,
827+
docCommentModuleName: String?,
802828
sourceLanguage: SourceLanguage,
803829
parameters: [(name: String, externalName: String?)],
804830
returnValue: SymbolGraph.Symbol.DeclarationFragments.Fragment
805831
) -> SymbolGraph {
806832
return makeSymbolGraph(
807-
moduleName: "ModuleName",
833+
moduleName: "ModuleName", // Don't use `docCommentModuleName` here.
808834
platform: platform,
809835
symbols: [
810836
makeSymbol(
@@ -813,6 +839,7 @@ class ParametersAndReturnValidatorTests: XCTestCase {
813839
kind: .func,
814840
pathComponents: ["functionName(...)"],
815841
docComment: docComment,
842+
moduleName: docCommentModuleName,
816843
location: (start, symbolURL),
817844
signature: .init(
818845
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)