Use IndexStoreDB for Symbol Resolution

[mattt]

Currently, swift-doc builds a symbol graph syntactically. However, this approach has limitations (#25, #16). We may want to keep the current, syntactic approach around as an option for quick-and-dirty doc generation, but in the long-term, we'll likely want to leverage IndexStoreDB for this.

[mattt]

Having dug into this a bit over the past few days, here's what I've learned:

• As it turns out, our current syntactic approach isn't inherently wrong. It just had a bug in its implementation (Fix SourceFile Visitor #51)
• IndexStoreDB can help, but it's not a panacea. Having USRs for symbols goes a long way to disambiguating relationships — especially across modules, but it's no substitute for the information we're getting from our syntactic parse.

Going forward, I think the best approach will be to take a progressive approach to doc generation. As a foundation, we start with a syntactic read of Swift code. If available, we then layer on information from IndexStoreDB (we might conditionalize certain features like symbol linking on the availability of this information). Finally, we might then pull in information from imported modules, like official docs for the Swift Standard Library or Foundation.

[MaxDesiatov]

I wonder if more detailed type information would help in any way. Some time ago I've attempted to implement a type inference engine for this type of dev tools (documentation generators, refactoring tools) etc, I wonder if it could be of some use. Especially as symbol resolution in Swift is exacerbated by the presence of overloads, shadowed symbols etc

[mattt]

Alternatively, we can load generated symbol graphs (JSON files generated by running swift dump-symbol-graph in Swift 5.3).