Fix api collection icon rendering

[RalucaP]

Bug/issue: rdar://135837611

Summary

This PR addresses an issue where API Collections were displaying incorrect icons in external references. The issue occurred when external references to API Collections were rendering with "role": "article" instead of "role": "collectionGroup", causing them to display article icons instead of the proper collection icons.

The implementation adds the missing .collectionGroup case to the renderKindAndRole function to ensure API Collections render consistently as articles with the collectionGroup role, displaying the correct collection icon in both main documents and external references.

Dependencies

None.

Testing

The functionality can be tested using the provided test case in DocumentationContentRendererTests.swift:

func testRenderKindAndRoleForAPICollection() throws {
    // API Collections should render as articles with collectionGroup role to display correct icon
    let (collectionKind, collectionRole) = DocumentationContentRenderer.renderKindAndRole(.collectionGroup, semantic: nil)
    XCTAssertEqual(collectionRole, "collectionGroup", "API Collections should have collectionGroup role for correct icon")
    
    // Verify other node types still work correctly
    let (articleKind, articleRole) = DocumentationContentRenderer.renderKindAndRole(.article, semantic: nil)
    XCTAssertEqual(articleKind, RenderNode.Kind.article)
    XCTAssertEqual(articleRole, "article")
    
    let (symbolKind, symbolRole) = DocumentationContentRenderer.renderKindAndRole(.class, semantic: nil)
    XCTAssertEqual(symbolKind, RenderNode.Kind.symbol)
    XCTAssertEqual(symbolRole, "symbol")
}

Checklist

• Updated tests
• Ran the ./bin/test script and it succeeded
• Updated documentation if necessary

[patshaughnessy]

This change looks good.

There are many different DocumentationNode.Kind values... have we tested if any other icons are incorrect?

[RalucaP]

Hi Pat, I made some changes to address the radar concerns for cross-framework API collection icons, can you please take another look?

There are many different DocumentationNode.Kind values... have we tested if any other icons are incorrect?

This radar is specific for API Collections, if more icons appear incorrect, we should fix them too, but probably in different PRs. :) Thanks!

[patshaughnessy]

Some minor suggestions. Thanks for the fix!

[patshaughnessy]

Suggested change

	let (kind, role) = DocumentationContentRenderer.renderKindAndRole(kind, semantic: nil, linkSummary: self)
	let (kind, role) = DocumentationContentRenderer.renderKindAndRole(kind, linkSummary: self)

You set the default value for semantic to be nil, so there's no need to pass that in here now.

[patshaughnessy]

Test looks good, but you might want to add another test for the case when taskGroups is nil, i.e. test that this continues to work for references to a normal article.

And what should happen if taskGroups is an empty array?

[d-ronnqvist]

We can't rely on the task groups information for this. Is there some other information that indicates that a external page is an API collection?

[d-ronnqvist]

The task groups of an link summary isn't a value that external documentation sources have to provide—and DocC doesn't include it in its link summaries unless specifically configured to do so—so it can't be reliably used to determine if an external page is an API collection or not.

[d-ronnqvist]

Question: Is there some other value about the link summary that we can use to determine if it's an API collection?

[RalucaP]

After analyzing the LinkDestinationSummary structure and the actual Apple documentation data, I found that there are no reliable alternatives to taskGroups for identifying API Collections in external references. The available fields (title patterns, URL patterns, abstract content, references) would all be fragile heuristics.
We could add an optional role to LinkDestinationSummary, but that would be a much larger change. Would you prefer that?

[d-ronnqvist]

The taskGroup information isn't a reliable source for this information. It's not requited for documentation sources to include it and we are also talking about removing it because the link summary isn't meant to be a representation of the documentation hierarchy.

[d-ronnqvist]

Is there another DocumentationNode.Kind value that API collection pages should be using? I see that we have both collection and collectionGroup but I don't recall what either of those are meant to represent. If not, should we introduce a dedicated "API Collection" kind and use that?

[patshaughnessy]

I believe collection is the root/framework page, and collectionGroup are API Collections or pages that groups symbol pages together.

[d-ronnqvist]

If I understand this correctly, this method is not expected to receive both a semantic and a link summary because one represents a local page and the other represents an external page. If we need a version that accepts a link summary we could consider having either a separate overload (that calls into a private common implementation) or a parameter that can be either a Semantic or a LinkDestinationSummary.

[sofiaromorales]

If it's not expected to pass both semantic and linkSummary at the same invocation call, let's split the method into two making them an overload.

The original

 static func renderKindAndRole(_ kind: DocumentationNode.Kind?, semantic: Semantic?) -> (RenderNode.Kind, String) {

and the overload

 static func renderKindAndRole(_ kind: DocumentationNode.Kind?, linkSummary: LinkDestinationSummary?) -> (RenderNode.Kind, String) {

Then the common logic can be encapsulated in another function.