SymbolKit
The specification and reference model for the Symbol Graph File Format.
A Symbol Graph models a module, also known in various programming languages as a "framework", "library", or "package", as a directed graph. In this graph, the nodes are declarations, and the edges connecting nodes are relationships between declarations.
To illustrate the shape of a symbol graph, take the following Swift code as a module called MyModule
:
public struct MyStruct {
public var x: Int
}
There are two nodes in this module's graph: the structure MyStruct
and its property, x
:
x
is related to MyStruct
: it is a member of MyStruct
. SymbolKit represents relationships as directed edges in the graph:
The source of an edge points to its target. You can read this edge as x
is a member of MyStruct
. Every edge is qualified by some kind of relationship; in this case, the kind is membership. There can be many kinds of relationships, even multiple relationships between the same two nodes. Here's another example, adding a Swift protocol to the mix:
public protocol P {}
public struct MyStruct: P {
public var x: Int
}
Now we've added a new node for the protocol P
, and a new conformance relationship between MyStruct
and P
:
By modeling different kinds of relationships, SymbolKit can provide rich data to power documentation, answering interesting questions, such as:
- Which types conform to this protocol?
- What is the class hierarchy rooted at this class?
- Which protocol provides a requirement called
count
? - Which types customize this protocol requirement?
In addition, graph representations of data also present opportunities for visualizations in documentation, illustrating the structure or hierarchy of a module.