apple/swift-docc-symbolkit

A Swift package for encoding and decoding Swift Symbol Graph files.

swift-docc-symbolkit's Issues

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

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.

[SR-15852] Add structural type data to symbol graph

Previous ID	SR-15852
Radar	None
Original Reporter	@WFT
Type	New Feature

Additional Detail from JIRA

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

md5: 5e91a1a29db3a0603ba5134fd34897a1

Issue Description:

Filed based on discussion on swift forums. Filed under "Swift-DocC" because there isn't a separate "SymbolKit" component.

Declarations/symbols (properties, methods, subscripts, etc.) should have their type information encoded as structural data. This helps with the goal of visualizing the connections between types and declarations.

An example: for the following declaration of bar(baz: ), we should be able to pull out both that the parameter baz takes an Optional with the generic Wrapped parameter substituted with String AND that the return type is a tuple with element .0 equal to Int and element .what equal to Array with the generic Element parameter substituted by UInt. For each type mentioned here I’d like to be able to pull out the USR/“precise identifier” of the type if there is one (i.e. not for the anonymous tuple) along with any generic parameters substituted.

struct Foo {
    func bar(baz: String?) -> (Int, what: [UInt]) { (0, what: []) }
}

Ideally I’d be able to draw out from the information above that given the result of calling bar(baz: ) I can get a UInt by accessing the Array subscript of the .what member. That requires being able to take the generic substitution map from [UInt] and apply it to a symbol like Array’s subscript. If I could then also connect that to Sequence.Element (so I can tell that iteration can also extract a UInt), that would be fantastic!

[SR-15551] Provide public API to access the available languages of both a symbol and a unified symbol graph

Previous ID	SR-15551
Radar	rdar://85982095
Original Reporter	@ethan-kusters
Type	Improvement

Additional Detail from JIRA

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

md5: dffbe7c5d5fcaa47f128391aa1a6450a

Issue Description:

SymbolKit should provide public API to access the available languages of both a symbol and a unified symbol graph.

We ran into the need for this in the work for mixed language support implemented here: https://github.com/apple/swift-docc/pull/47/files.

[SR-15982] SymbolKit crashes when encoding unknown mixins

Previous ID	SR-15982
Radar	rdar://problem/90348996
Original Reporter	@franklinsch
Type	Improvement

Additional Detail from JIRA

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

md5: 7a780d28224eef5a62504852074094c5

Issue Description:

SymbolKit decodes unknown Symbol mixins just fine by adding them to Symbol.mixins, but {{fatalError}}s when encoding unknown mixins: https://github.com/apple/swift-docc-symbolkit/blob/main/Sources/SymbolKit/SymbolGraph/Symbol/Symbol.swift#L180.

For example, when decoding a symbol graph from the Swift compiler (which includes the location mixin) and encoding it back, SymbolKit crashes.

We should make SymbolKit encode unknown mixins.

[SR-15570] SymbolKit: Parse symbol kinds with a known language

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

Additional Detail from JIRA

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

md5: a769a8f20a3a2a1a27d0ea7853785b56

Issue Description:

Currently, symbol kinds are parsed by comparing the kind string against a list of known symbol kinds, first as a whole and then with the first component discarded. However, this relies on the assumption that the first component of a symbol kind is a language identifier (e.g. `swift.func`). To prevent accidental loss of data, we should figure out a way to parse symbol kinds by taking their interface language into account.

The main problem here is the structure of the Decodable protocol: Each type's implementation is run in isolation, without taking into account the rest of the data being decoded. This will need to be handled somehow if we want to handle this.

Add attribute to identify a synthesized symbol

In tools that operate on symbol graph files it can sometimes be useful to know if a given synthesized symbol is synthesized or not.

For Swift symbols one can check if the symbol's unique identifier contains "::SYNTHESIZED::" but this is relying on an implementation detail and isn't applicable to symbols in other source languages.