[Overloads] Do not automatically curate overloaded symbols, in favor of their overload group (#864)

rdar://117768214

Author: QuietMisdreavus

Sources/SwiftDocC/Infrastructure/DocumentationContext.swift

@@ -1430,6 +1430,14 @@ public class DocumentationContext: DocumentationContextDataProviderDelegate {
                     localCache: documentationCache,
                     engine: diagnosticEngine
                 )
+            case .overloadOf:
+                // Build overload <-> overloadGroup relationships.
+                SymbolGraphRelationshipsBuilder.addOverloadRelationship(
+                    edge: edge,
+                    context: self,
+                    localCache: documentationCache,
+                    engine: diagnosticEngine
+                )
             default:
                 break
             }

Sources/SwiftDocC/Infrastructure/Link Resolution/PathHierarchy.swift

@@ -141,7 +141,7 @@ struct PathHierarchy {
                 // An 'overloadOf' relationship points from symbol -> group. We want to disfavor the
                 // individual overload symbols in favor of resolving links to their overload group
                 // symbol.
-                nodes[relationship.source]?.specialBehaviors.insert(.disfavorInLinkCollision)
+                nodes[relationship.source]?.specialBehaviors.formUnion([.disfavorInLinkCollision, .excludeFromAutomaticCuration])
             }
 
             // If there are multiple symbol graphs (for example for different source languages or platforms) then the nodes may have already been added to the hierarchy.

Sources/SwiftDocC/Infrastructure/Symbol Graph/SymbolGraphRelationshipsBuilder.swift

@@ -430,4 +430,28 @@ struct SymbolGraphRelationshipsBuilder {
             constraint: newConstraint
         )
     }
+
+    static func addOverloadRelationship(
+        edge: SymbolGraph.Relationship,
+        context: DocumentationContext,
+        localCache: DocumentationContext.LocalCache,
+        engine: DiagnosticEngine
+    ) {
+        guard let overloadNode = localCache[edge.source] else {
+            engine.emit(NodeProblem.notFound(edge.source))
+            return
+        }
+        guard let overloadGroupNode = localCache[edge.target] else {
+            engine.emit(NodeProblem.notFound(edge.target))
+            return
+        }
+
+        guard let overloadTopicGraphNode = context.topicGraph.nodes[overloadNode.reference],
+              let overloadGroupTopicGraphNode = context.topicGraph.nodes[overloadGroupNode.reference]
+        else {
+            return
+        }
+        overloadGroupTopicGraphNode.isOverloadGroup = true
+        context.topicGraph.addEdge(from: overloadGroupTopicGraphNode, to: overloadTopicGraphNode)
+    }
 }

Sources/SwiftDocC/Infrastructure/Topic Graph/TopicGraph.swift

@@ -98,7 +98,10 @@ struct TopicGraph {
 
         /// If true, the topic has been manually organized into a topic section on some other page.
         var isManuallyCurated: Bool = false
-        
+
+        /// If true, this topic is a generated "overload group" symbol page.
+        var isOverloadGroup: Bool = false
+
         init(reference: ResolvedTopicReference, kind: DocumentationNode.Kind, source: ContentLocation, title: String, isResolvable: Bool = true, isVirtual: Bool = false, isEmptyExtension: Bool = false, isManuallyCurated: Bool = false) {
             self.reference = reference
             self.kind = kind
@@ -321,6 +324,16 @@ struct TopicGraph {
         }
     }
 
+    /// Returns the children of this node that reference it as their overload group.
+    func overloads(of groupReference: ResolvedTopicReference) -> [ResolvedTopicReference]? {
+        guard nodes[groupReference]?.isOverloadGroup == true else {
+            return nil
+        }
+        return edges[groupReference, default: []].filter({ childReference in
+            nodes[childReference]?.isManuallyCurated == false
+        })
+    }
+
     /// Returns true if a node exists with the given reference and it's set as linkable.
     func isLinkable(_ reference: ResolvedTopicReference) -> Bool {
         // Sections (represented by the node path + fragment with the section name)

Sources/SwiftDocC/LinkTargets/LinkDestinationSummary.swift

@@ -333,7 +333,13 @@ public extension DocumentationNode {
             case .tutorial, .tutorialArticle, .technology, .technologyOverview, .chapter, .volume, .onPageLandmark:
                 taskGroups = [.init(title: nil, identifiers: context.children(of: reference).map { $0.reference.absoluteString })]
             default:
-                taskGroups = renderNode.topicSections.map { group in .init(title: group.title, identifiers: group.identifiers) }
+                var topicSectionGroups: [LinkDestinationSummary.TaskGroup] = renderNode.topicSections.map { group in .init(title: group.title, identifiers: group.identifiers) }
+
+                if let overloadChildren = context.topicGraph.overloads(of: self.reference), !overloadChildren.isEmpty {
+                    topicSectionGroups.append(.init(title: "Overloads", identifiers: overloadChildren.map(\.absoluteString)))
+                }
+
+                taskGroups = topicSectionGroups
                 for variant in renderNode.topicSectionsVariants.variants {
                     taskGroupVariants[variant.traits] = variant.applyingPatchTo(renderNode.topicSections).map { group in .init(title: group.title, identifiers: group.identifiers) }
                 }

Tests/SwiftDocCTests/Indexing/NavigatorIndexTests.swift

@@ -1621,6 +1621,25 @@ Root
         )
     }
 
+    func testNavigatorDoesNotContainOverloads() throws {
+        enableFeatureFlag(\.isExperimentalOverloadedSymbolPresentationEnabled)
+
+        let navigatorIndex = try generatedNavigatorIndex(
+            for: "OverloadedSymbols",
+            bundleIdentifier: "com.shapes.ShapeKit")
+
+        let protocolID = try XCTUnwrap(navigatorIndex.id(for: "/documentation/shapekit/overloadedprotocol", with: .swift))
+        let protocolNode = try XCTUnwrap(search(node: navigatorIndex.navigatorTree.root) { $0.id == protocolID })
+        XCTAssertEqual(protocolNode.children.map(\.item.title), [
+            "Instance Methods",
+            "func fourthTestMemberName(test:)",
+        ])
+
+        let overloadGroupID = try XCTUnwrap(navigatorIndex.id(for: "/documentation/shapekit/overloadedprotocol/fourthtestmembername(test:)-9b6be", with: .swift))
+        let overloadGroupNode = try XCTUnwrap(search(node: navigatorIndex.navigatorTree.root) { $0.id == overloadGroupID })
+        XCTAssert(overloadGroupNode.children.isEmpty)
+    }
+
     func generatedNavigatorIndex(for testBundleName: String, bundleIdentifier: String) throws -> NavigatorIndex {
         let (bundle, context) = try testBundleAndContext(named: testBundleName)
         let renderContext = RenderContext(documentationContext: context, bundle: bundle)

Tests/SwiftDocCTests/Infrastructure/AutomaticCurationTests.swift

@@ -669,6 +669,74 @@ class AutomaticCurationTests: XCTestCase {
             ]
         )
     }
+
+    func testOverloadedSymbolsAreCuratedUnderGroup() throws {
+        enableFeatureFlag(\.isExperimentalOverloadedSymbolPresentationEnabled)
+
+        let protocolRenderNode = try renderNode(
+            atPath: "/documentation/ShapeKit/OverloadedProtocol",
+            fromTestBundleNamed: "OverloadedSymbols")
+
+        guard protocolRenderNode.topicSections.count == 1, let protocolTopicSection = protocolRenderNode.topicSections.first else {
+            XCTFail("Expected to find 1 topic section, found \(protocolRenderNode.topicSections.count): \(protocolRenderNode.topicSections.map(\.title?.singleQuoted))")
+            return
+        }
+
+        XCTAssertEqual(protocolTopicSection.title, "Instance Methods")
+        XCTAssertEqual(protocolTopicSection.identifiers, [
+            "doc://com.shapes.ShapeKit/documentation/ShapeKit/OverloadedProtocol/fourthTestMemberName(test:)-9b6be"
+        ])
+
+        let overloadGroupRenderNode = try renderNode(
+            atPath: "/documentation/ShapeKit/OverloadedProtocol/fourthTestMemberName(test:)-9b6be",
+            fromTestBundleNamed: "OverloadedSymbols")
+
+        XCTAssertEqual(
+            overloadGroupRenderNode.topicSections.count, 0,
+            "Expected no topic sections, found \(overloadGroupRenderNode.topicSections.map(\.title?.singleQuoted))"
+        )
+    }
+
+    func testAutomaticCurationHandlesOverloadsWithLanguageFilters() throws {
+        enableFeatureFlag(\.isExperimentalOverloadedSymbolPresentationEnabled)
+
+        let (bundle, context) = try testBundleAndContext(named: "OverloadedSymbols")
+
+        let protocolDocumentationNode = try context.entity(
+            with: .init(
+                bundleIdentifier: bundle.identifier,
+                path: "/documentation/ShapeKit/OverloadedProtocol",
+                sourceLanguage: .swift))
+
+        func assertAutomaticCuration(
+            variants: Set<DocumentationDataVariantsTrait>,
+            file: StaticString = #file,
+            line: UInt = #line
+        ) throws {
+            let topics = try AutomaticCuration.topics(
+                for: protocolDocumentationNode,
+                withTraits: variants,
+                context: context)
+
+            guard topics.count == 1, let overloadTopic = topics.first else {
+                XCTFail(
+                    "Expected one automatic curation topic, found \(topics.count): \(topics.map(\.title?.singleQuoted))",
+                    file: file, line: line)
+                return
+            }
+
+            XCTAssertEqual(overloadTopic.title, "Instance Methods", file: file, line: line)
+            XCTAssertEqual(overloadTopic.references.map(\.absoluteString), [
+                "doc://com.shapes.ShapeKit/documentation/ShapeKit/OverloadedProtocol/fourthTestMemberName(test:)-9b6be"
+            ], file: file, line: line)
+        }
+
+        // AutomaticCuration uses a different method for collecting child nodes when the variant
+        // traits set is empty and when it's not. Ensure that in both cases, we only see the
+        // overload group symbol curated under the protocol symbol.
+        try assertAutomaticCuration(variants: [])
+        try assertAutomaticCuration(variants: [.swift])
+    }
 }
 
 private func makeSymbol(

Tests/SwiftDocCTests/Infrastructure/PathHierarchyTests.swift

@@ -1248,6 +1248,41 @@ class PathHierarchyTests: XCTestCase {
                        "/ShapeKit/OverloadedEnum/firstTestMemberName(_:)-88rbf")
     }
 
+    func testOverloadedSymbolsWithOverloadGroups() throws {
+        enableFeatureFlag(\.isExperimentalOverloadedSymbolPresentationEnabled)
+
+        let (_, context) = try testBundleAndContext(named: "OverloadedSymbols")
+        let tree = context.linkResolver.localResolver.pathHierarchy
+
+        let paths = tree.caseInsensitiveDisambiguatedPaths()
+
+        XCTAssertEqual(paths["s:8ShapeKit22OverloadedParentStructV"],
+                       "/ShapeKit/OverloadedParentStruct-1jr3p")
+        XCTAssertEqual(paths["s:8ShapeKit22overloadedparentstructV"],
+                       "/ShapeKit/overloadedparentstruct-6a7lx")
+
+        // These need to be disambiguated in two path components
+        XCTAssertEqual(paths["s:8ShapeKit22OverloadedParentStructV15fifthTestMemberSivpZ"],
+                       "/ShapeKit/OverloadedParentStruct-1jr3p/fifthTestMember")
+        XCTAssertEqual(paths["s:8ShapeKit22overloadedparentstructV15fifthTestMemberSivp"],
+                       "/ShapeKit/overloadedparentstruct-6a7lx/fifthTestMember")
+
+        // This is the only enum case and can be disambiguated as such
+        XCTAssertEqual(paths["s:8ShapeKit14OverloadedEnumO19firstTestMemberNameyACSScACmF"],
+                       "/ShapeKit/OverloadedEnum/firstTestMemberName(_:)-enum.case")
+        // These are all methods and can only be disambiguated with the USR hash
+        XCTAssertEqual(paths["s:8ShapeKit14OverloadedEnumO19firstTestMemberNameySdSiF"],
+                       "/ShapeKit/OverloadedEnum/firstTestMemberName(_:)-14g8s")
+        XCTAssertEqual(paths["s:8ShapeKit14OverloadedEnumO19firstTestMemberNameySdSfF"],
+                       "/ShapeKit/OverloadedEnum/firstTestMemberName(_:)-14ife")
+        XCTAssertEqual(paths["s:8ShapeKit14OverloadedEnumO19firstTestMemberNameySdSSF"],
+                       "/ShapeKit/OverloadedEnum/firstTestMemberName(_:)-14ob0")
+        XCTAssertEqual(paths["s:8ShapeKit14OverloadedEnumO19firstTestMemberNameyS2dF"],
+                       "/ShapeKit/OverloadedEnum/firstTestMemberName(_:)-4ja8m")
+        XCTAssertEqual(paths["s:8ShapeKit14OverloadedEnumO19firstTestMemberNameySdSaySdGF"],
+                       "/ShapeKit/OverloadedEnum/firstTestMemberName(_:)-88rbf")
+    }
+
     func testOverloadGroupSymbolsResolveLinksWithoutHash() throws {
         enableFeatureFlag(\.isExperimentalOverloadedSymbolPresentationEnabled)
 

Tests/SwiftDocCTests/Infrastructure/TopicGraphTests.swift

@@ -57,6 +57,36 @@ class TopicGraphTests: XCTestCase {
             graph.addEdge(from: testNodeWithTitle("C"), to: testNodeWithTitle("A"))
             return graph
         }
+
+        /// Return a graph with overload group information:
+        ///
+        /// ```
+        /// Parent
+        ///   -> A
+        ///   -> B
+        ///   -> Overload Group
+        ///     -> A
+        ///     -> B
+        /// ```
+        static var withOverloadGroup: TopicGraph {
+            var graph = TopicGraph()
+
+            let parent = testNodeWithTitle("Parent")
+            let group = testNodeWithTitle("Overload Group")
+            let a = testNodeWithTitle("A")
+            let b = testNodeWithTitle("B")
+
+            graph.addEdge(from: parent, to: a)
+            graph.addEdge(from: parent, to: b)
+            graph.addEdge(from: parent, to: group)
+
+            graph.addEdge(from: group, to: a)
+            graph.addEdge(from: group, to: b)
+
+            graph.nodes[group.reference]?.isOverloadGroup = true
+
+            return graph
+        }
     }
     func testNodes() {
         XCTAssertEqual(1, TestGraphs.withOneNode.nodes.count)
@@ -274,4 +304,14 @@ class TopicGraphTests: XCTestCase {
             }
         }
     }
+
+    func testCollectOverloads() {
+        let graph = TestGraphs.withOverloadGroup
+        let overloadGroup = TestGraphs.testNodeWithTitle("Overload Group")
+
+        XCTAssertEqual(graph.overloads(of: overloadGroup.reference), [
+            TestGraphs.testNodeWithTitle("A").reference,
+            TestGraphs.testNodeWithTitle("B").reference,
+        ])
+    }
 }