[SR-16111] [SymbolKit] Provide a simplified method for reading a symbol's or relationship's mixins

[QuietMisdreavus]

Previous ID	SR-16111
Radar	None
Original Reporter	@QuietMisdreavus
Type	Improvement

Additional Detail from JIRA

Votes	0
Component/s	Swift-DocC
Labels	Improvement
Assignee	None
Priority	Medium

md5: 9c3463d48a54fbd06e0e7b6bba7d89d2

Issue Description:

SymbolKit currently defines optional data fields for symbols and relationships as a set of "mixins", which is represented as a map from a "mixin key" to the parsed value of that mixin. Swift-DocC uses these mixins for various uses, but checking for a value and reading it out is a bit cumbersome. For example, this is how Swift-DocC loads availability information from a symbol:

if var availability = symbol.mixins[SymbolGraph.Symbol.Availability.mixinKey] as? SymbolGraph.Symbol.Availability

This could be greatly simplified into some kind of getMixin method on symbols and relationships in SymbolKit. It could look something like this:

func getMixin<T>() -> T? where T: Mixin {
    self.mixins[T.mixinKey] as? T
}

In fact, Swift-DocC already defines something similar, as an extension on mixin dictionaries themselves:

extension Dictionary where Key == String, Value == Mixin {
    func getValueIfPresent<T>(for mixinType: T.Type) -> T? where T: Mixin {
        return self[mixinType.mixinKey] as? T
    }
}

Adding one of these methods to SymbolKit and encouraging its use throughout Swift-DocC would make its codebase much more readable.

[QuietMisdreavus]

@shahmishal This should be transferred to swift-docc-symbolkit.

[theMomax]

swiftlang/swift-docc-symbolkit#39 added a subscript which does just that on Symbol and Relationship:

Usage example:

if let declarationFragments = mySymbol[mixin: SymbolGraph.Symbol.DeclarationFragments.self] {
    // ...
}

I think this can therefore be closed.

[QuietMisdreavus]

cc @d-ronnqvist who was also looking into this last week

I think David wanted a version that force-casted the mixin to the mixin type if the key was present, and/or provide a debug assertion on it, but Max's patch definitely fits the spirit of what i was asking for originally.

I'm going to close this issue as resolved, but @d-ronnqvist can chime in with more details if he wants.

[d-ronnqvist]

Yes, I agree with closing this issue as resolved.

At one point I was thinking that perhaps the subscript should assert in debug builds that the generic mix-in for a given key is of that generic type. As far as I'm aware this should always hold true for all the built-in mix-ins.

That said, we can always consider something like that in the future if we run into issues with mix-ins unexpectedly returning nil due to key collisions or data format version differences.