From 7144d305777baf704d578c1e76305df076014484 Mon Sep 17 00:00:00 2001 From: Raluca Pintilii Pereira Coutinho Date: Thu, 20 Nov 2025 17:47:57 +0100 Subject: [PATCH 1/2] Add test for API Collection icon rendering in external references Adds test to verify that API Collections (articles with Topics sections) are correctly identified as .collectionGroup kind in linkable entities, ensuring cross-framework references display the correct icon. The test is temporarily skipped until the fix is implemented in the next commit. rdar://135837611 --- .../LinkDestinationSummaryTests.swift | 49 +++++++++++++++++++ 1 file changed, 49 insertions(+) diff --git a/Tests/SwiftDocCTests/LinkTargets/LinkDestinationSummaryTests.swift b/Tests/SwiftDocCTests/LinkTargets/LinkDestinationSummaryTests.swift index 5ac4655d92..1150d6ddd9 100644 --- a/Tests/SwiftDocCTests/LinkTargets/LinkDestinationSummaryTests.swift +++ b/Tests/SwiftDocCTests/LinkTargets/LinkDestinationSummaryTests.swift @@ -829,4 +829,53 @@ class LinkDestinationSummaryTests: XCTestCase { "doc://com.example.mymodule/documentation/MyModule/MyClass/myFunc()-9a7po", ]) } + + /// Tests that API Collections (articles with Topics sections) are correctly identified as `.collectionGroup` + /// kind in linkable entities, ensuring cross-framework references display the correct icon. + func testAPICollectionKindForLinkDestinationSummary() async throws { + throw XCTSkip("Test will be enabled after implementing the fix") + + let symbolGraph = makeSymbolGraph( + moduleName: "TestModule", + symbols: [makeSymbol(id: "test-class", kind: .class, pathComponents: ["TestClass"])] + ) + + let catalogHierarchy = Folder(name: "unit-test.docc", content: [ + TextFile(name: "APICollection.md", utf8Content: """ + # Time Pitch Algorithm Settings + + This is an API Collection that curates symbols. + + ## Topics + + ### Algorithms + - ``TestModule/TestClass`` + """), + JSONFile(name: "TestModule.symbols.json", content: symbolGraph), + InfoPlist(displayName: "TestBundle", identifier: "com.test.example") + ]) + + let (_, context) = try await loadBundle(catalog: catalogHierarchy) + let converter = DocumentationNodeConverter(context: context) + + let apiCollectionReference = ResolvedTopicReference( + bundleID: context.inputs.id, + path: "/documentation/TestBundle/APICollection", + sourceLanguage: .swift + ) + let node = try context.entity(with: apiCollectionReference) + let renderNode = converter.convert(node) + + let summaries = node.externallyLinkableElementSummaries(context: context, renderNode: renderNode) + let pageSummary = summaries[0] + + XCTAssertEqual(pageSummary.kind, .collectionGroup) + XCTAssertEqual(pageSummary.title, "Time Pitch Algorithm Settings") + XCTAssertEqual(pageSummary.abstract, [.text("This is an API Collection that curates symbols.")]) + + // Verify round-trip encoding preserves the correct kind + let encoded = try JSONEncoder().encode(pageSummary) + let decoded = try JSONDecoder().decode(LinkDestinationSummary.self, from: encoded) + XCTAssertEqual(decoded.kind, .collectionGroup) + } } From c7d498f191eeaef5fe1bd5982e410f24faed0f86 Mon Sep 17 00:00:00 2001 From: Raluca Pintilii Pereira Coutinho Date: Thu, 20 Nov 2025 17:59:23 +0100 Subject: [PATCH 2/2] Fix API Collection icon rendering for external references Ensures API Collections are correctly identified as collectionGroup kind in linkable entities by using DocumentationContentRenderer.roleForArticle logic. This fixes cross-framework references where API Collections were incorrectly showing Article icons instead of Collection Group icons. rdar://135837611 --- .../LinkTargets/LinkDestinationSummary.swift | 13 ++++++++++++- .../LinkTargets/LinkDestinationSummaryTests.swift | 2 -- 2 files changed, 12 insertions(+), 3 deletions(-) diff --git a/Sources/SwiftDocC/LinkTargets/LinkDestinationSummary.swift b/Sources/SwiftDocC/LinkTargets/LinkDestinationSummary.swift index 993e8fb315..911163c327 100644 --- a/Sources/SwiftDocC/LinkTargets/LinkDestinationSummary.swift +++ b/Sources/SwiftDocC/LinkTargets/LinkDestinationSummary.swift @@ -1017,7 +1017,18 @@ private extension DocumentationNode { // specialized articles, like sample code pages, that benefit from being treated as articles in // some parts of the compilation process (like curation) but not others (like link destination // summary creation and render node translation). - return metadata?.pageKind?.kind.documentationNodeKind ?? kind + let baseKind = metadata?.pageKind?.kind.documentationNodeKind ?? kind + + // For articles, check if they should be treated as API Collections (collectionGroup). + // This ensures that linkable entities have the same kind detection logic as the rendering system, + // fixing cross-framework references where API Collections were incorrectly showing as articles. + if baseKind == .article, + let article = semantic as? Article, + DocumentationContentRenderer.roleForArticle(article, nodeKind: kind) == .collectionGroup { + return .collectionGroup + } + + return baseKind } } diff --git a/Tests/SwiftDocCTests/LinkTargets/LinkDestinationSummaryTests.swift b/Tests/SwiftDocCTests/LinkTargets/LinkDestinationSummaryTests.swift index 1150d6ddd9..882c9f1014 100644 --- a/Tests/SwiftDocCTests/LinkTargets/LinkDestinationSummaryTests.swift +++ b/Tests/SwiftDocCTests/LinkTargets/LinkDestinationSummaryTests.swift @@ -833,8 +833,6 @@ class LinkDestinationSummaryTests: XCTestCase { /// Tests that API Collections (articles with Topics sections) are correctly identified as `.collectionGroup` /// kind in linkable entities, ensuring cross-framework references display the correct icon. func testAPICollectionKindForLinkDestinationSummary() async throws { - throw XCTSkip("Test will be enabled after implementing the fix") - let symbolGraph = makeSymbolGraph( moduleName: "TestModule", symbols: [makeSymbol(id: "test-class", kind: .class, pathComponents: ["TestClass"])]