Improve the core link resolution implementation

[d-ronnqvist]

Enhancement Request: Improve the core link resolution implementation

Description:

Resolving symbol links and documentation links is a core feature and core component of Swift-DocC. There are a handful of user-facing improvements that we'd like to make—better error messages, reducing the number of cases where links need to be disambiguated, allowing over-disambiguated links to resolve, supporting more characters in links, and more—but these enhancements are more difficult to add to the current link resolution implementation. To make it easier to implement these enhancements and more in the future, we should improve on the core link resolution implementation to address the limitations that made these enhancements difficult to implement.

Motivation:

Improving the core link resolution system in Swift-DocC will make it easier to make other improvements to the user facing link resolution functionality.

Importance:

The only importance of this enhancement comes from the other changes that it makes easier to implement. None of them are major on their own, but together they add up to meaningful improvements.

[d-ronnqvist]

One of these improvements is to allow links to be over-disambiguated.

Currently symbol links must be written with the fewest disambiguations—as determined by DocC—for the links to resolve. Links with too little or too much disambiguation won't resolve.

The latter (too much disambiguation) may seem unimportant, but allowing links to be over-disambiguated enable future improvements that reduce the necessary disambiguation without breaking existing links.

[d-ronnqvist]

Another important improvement to the link resolution system is that it should keep track of enough information to be able to distinguish between different reasons that a link failed to resolve to allow for different diagnostics for each failure reason.

[d-ronnqvist]

I've already prototypes these changes here #251. Now the plan is to start landing these improvements side-by-side with the current link resolution implementation, as outlined in this message.