prefer longer doc comments when selecting commented symbols (#1258)

rdar://156595902

Author: QuietMisdreavus

Sources/SwiftDocC/Semantics/Symbol/UnifiedSymbol+Extensions.swift

@@ -93,11 +93,31 @@ extension UnifiedSymbolGraph.Symbol {
 
     /// Returns the primary symbol selector to use as documentation source.
     var documentedSymbolSelector: UnifiedSymbolGraph.Selector? {
-        // We'll prioritize the first documented 'swift' symbol, if we have
-        // one.
-        return docComment.keys.first { selector in
-            return selector.interfaceLanguage == "swift"
-        } ?? docComment.keys.first
+        // Prioritize the longest doc comment with a "swift" selector,
+        // if there is one.
+        return docComment.min(by: { lhs, rhs in
+            if (lhs.key.interfaceLanguage == "swift") != (rhs.key.interfaceLanguage == "swift") {
+                // sort swift selectors before non-swift ones
+                return lhs.key.interfaceLanguage == "swift"
+            }
+
+            // if the comments are equal, bail early without iterating them again
+            guard lhs.value != rhs.value else {
+                return false
+            }
+
+            let lhsLength = lhs.value.lines.totalCount
+            let rhsLength = rhs.value.lines.totalCount
+
+            if lhsLength == rhsLength {
+                // if the comments are the same length, just sort them lexicographically
+                return lhs.value.lines.isLexicographicallyBefore(rhs.value.lines)
+            } else {
+                // otherwise, sort by the length of the doc comment,
+                // so that `min` returns the longest comment
+                return lhsLength > rhsLength
+            }
+        })?.key
     }
 
     func identifier(forLanguage interfaceLanguage: String) -> SymbolGraph.Symbol.Identifier {
@@ -115,3 +135,15 @@ extension UnifiedSymbolGraph.Symbol {
         }
     }
 }
+
+extension [SymbolGraph.LineList.Line] {
+    fileprivate var totalCount: Int {
+        return reduce(into: 0) { result, line in
+            result += line.text.count
+        }
+    }
+
+    fileprivate func isLexicographicallyBefore(_ other: Self) -> Bool {
+        self.lexicographicallyPrecedes(other) { $0.text < $1.text }
+    }
+}

Tests/SwiftDocCTests/Infrastructure/DocumentationContext/DocumentationContextTests.swift

@@ -1056,7 +1056,127 @@ class DocumentationContextTests: XCTestCase {
                        └─ Text "Return value"
                        """)
     }
-    
+
+    func testLoadsConflictingDocComments() async throws {
+        let macOSSymbolGraph = makeSymbolGraph(
+            moduleName: "TestProject",
+            platform: .init(operatingSystem: .init(name: "macOS")),
+            symbols: [
+                makeSymbol(
+                    id: "TestSymbol",
+                    kind: .func,
+                    pathComponents: ["TestSymbol"],
+                    docComment: "This is a comment.",
+                    otherMixins: [
+                        SymbolGraph.Symbol.DeclarationFragments(declarationFragments: [
+                            .init(
+                                kind: .text,
+                                spelling: "TestSymbol Mac",
+                                preciseIdentifier: nil)
+                        ])
+                    ])
+            ])
+        let iOSSymbolGraph = makeSymbolGraph(
+            moduleName: "TestProject",
+            platform: .init(operatingSystem: .init(name: "iOS")),
+            symbols: [
+                makeSymbol(
+                    id: "TestSymbol",
+                    kind: .func,
+                    pathComponents: ["TestSymbol"],
+                    docComment: "This is a longer comment that should be shown instead.",
+                    otherMixins: [
+                        SymbolGraph.Symbol.DeclarationFragments(declarationFragments: [
+                            .init(
+                                kind: .text,
+                                spelling: "TestSymbol iOS",
+                                preciseIdentifier: nil)
+                        ])
+                    ])
+            ])
+
+        for forwards in [true, false] {
+            let catalog = Folder(name: "unit-test.docc", content: [
+                InfoPlist(displayName: "TestProject", identifier: "com.test.example"),
+                JSONFile(name: "symbols\(forwards ? "1" : "2").symbols.json", content:macOSSymbolGraph),
+                JSONFile(name: "symbols\(forwards ? "2" : "1").symbols.json", content: iOSSymbolGraph),
+            ])
+
+            let (bundle, context) = try await loadBundle(catalog: catalog)
+
+            let reference = ResolvedTopicReference(
+                bundleID: bundle.id,
+                path: "/documentation/TestProject/TestSymbol",
+                sourceLanguage: .swift
+            )
+            let symbol = try XCTUnwrap(context.entity(with: reference).semantic as? Symbol)
+            let abstract = try XCTUnwrap(symbol.abstractSection)
+            XCTAssertEqual(
+                abstract.paragraph.plainText,
+                "This is a longer comment that should be shown instead.")
+        }
+    }
+
+    func testLoadsConflictingDocCommentsOfSameLength() async throws {
+        let macOSSymbolGraph = makeSymbolGraph(
+            moduleName: "TestProject",
+            platform: .init(operatingSystem: .init(name: "macOS")),
+            symbols: [
+                makeSymbol(
+                    id: "TestSymbol",
+                    kind: .func,
+                    pathComponents: ["TestSymbol"],
+                    docComment: "Comment A.",
+                    otherMixins: [
+                        SymbolGraph.Symbol.DeclarationFragments(declarationFragments: [
+                            .init(
+                                kind: .text,
+                                spelling: "TestSymbol Mac",
+                                preciseIdentifier: nil)
+                        ])
+                    ])
+            ])
+        let iOSSymbolGraph = makeSymbolGraph(
+            moduleName: "TestProject",
+            platform: .init(operatingSystem: .init(name: "iOS")),
+            symbols: [
+                makeSymbol(
+                    id: "TestSymbol",
+                    kind: .func,
+                    pathComponents: ["TestSymbol"],
+                    docComment: "Comment B.",
+                    otherMixins: [
+                        SymbolGraph.Symbol.DeclarationFragments(declarationFragments: [
+                            .init(
+                                kind: .text,
+                                spelling: "TestSymbol iOS",
+                                preciseIdentifier: nil)
+                        ])
+                    ])
+            ])
+
+        for forwards in [true, false] {
+            let catalog = Folder(name: "unit-test.docc", content: [
+                InfoPlist(displayName: "TestProject", identifier: "com.test.example"),
+                JSONFile(name: "symbols\(forwards ? "1" : "2").symbols.json", content:macOSSymbolGraph),
+                JSONFile(name: "symbols\(forwards ? "2" : "1").symbols.json", content: iOSSymbolGraph),
+            ])
+
+            let (bundle, context) = try await loadBundle(catalog: catalog)
+
+            let reference = ResolvedTopicReference(
+                bundleID: bundle.id,
+                path: "/documentation/TestProject/TestSymbol",
+                sourceLanguage: .swift
+            )
+            let symbol = try XCTUnwrap(context.entity(with: reference).semantic as? Symbol)
+            let abstract = try XCTUnwrap(symbol.abstractSection)
+            XCTAssertEqual(
+                abstract.paragraph.plainText,
+                "Comment A.")
+        }
+    }
+
     func testMergesMultipleSymbolDeclarations() async throws {
         let graphContentiOS = try String(contentsOf: Bundle.module.url(
             forResource: "LegacyBundle_DoNotUseInNewTests", withExtension: "docc", subdirectory: "Test Bundles")!