Support disambiguating links with type signature information

[d-ronnqvist]

Bug/issue #, if applicable: rdar://112224233

Summary

Adds support for disambiguating symbol links with information from the symbol graph's functionSignature data.

This new syntax was pitched on the Swift Forums in this thread.

With these changes DocC will support type signature disambiguation in links and will use it in diagnostics but topic references and page URLs will continue to only use kind-and-hash disambiguation to ensure that all pages have the same URLs as without these changes.

Dependencies

None.

Testing

Describe how a reviewer can test the functionality of your PR. Provide test content to test with if
applicable.

Steps:

1. Provide setup instructions.
2. Explain in detail how the functionality can be tested.

Checklist

Make sure you check off the following items. If they cannot be completed, provide a reason.

• Added tests
• Ran the ./bin/test script and it succeeded
• Updated documentation if necessary

[d-ronnqvist]

I feel that the code in this PR is getting too long to be easily reviewed but splitting it into multiple files in the same PR makes it much much harder to know what changed and what moved. Because of this I opened #662 to only split the code into multiple files and then this PR can focus on just the new feature.

[d-ronnqvist]

I'm breaking this up into smaller pieces (#824 and #828) so that there won't be as many merge conflicts to deal with. I'll rebase this PR once both those have been merged.

[d-ronnqvist]

The main implementation is ready for review. I will update the user facing documentation to describe this new syntax.

[d-ronnqvist]

@swift-ci please test

[d-ronnqvist]

@swift-ci please test

[d-ronnqvist]

I resolved the merge conflicts so this is reviewable again.

I also updated the code to make some improvements for overload groups and C++ operators which are new changes since last time I updated this PR.

[d-ronnqvist]

I have some more improvements in mind for the richness of the error messages about ambiguous links, but my plan is to defer that to a follow up PR, sometime after this is merged 🤞

[patshaughnessy]

Amazing work!

I left a lot of questions and a few suggestions mostly around the readability of the code. You added extensive new unit tests, which is great, but I can imagine some quirks or odd corner conditions could come up someday. I'd suggest we merge this and then keep an eye on how the disambiguation is working over time as we use these new disambiguation styles more and more.

[patshaughnessy]

Following on the previous comment: Here you set the values for these to false and true. It might be hard for someone in the future to track down where you set these values. Maybe using FeatureFlags or maybe some struct-wide attribute of PathHierarchy instead of function parameters would make the code less verbose and easier to understand?

[d-ronnqvist]

I'm not too concerned about this since these are mostly file private arguments that are passed by the caller.

[daniel-grumberg]

I am not sure I understand what this is referring to.

[d-ronnqvist]

The default diagnostic formatter outputs diagnostic solutions (phrased as "suggestions") on a single line. For example:

4 | /// Here's a link that uses the wrong symbol kind disambiguation in a link:
5 + /// - ``myFunction(with:and:)-struct``
  |                              ╰─suggestion: Remove '-struct' for'func myFunction(with one: Int, and two: String) -> Bool'

If you look closely at the suggestion text you can see that there's a missing space between "for" and the symbol name.

With these changes this suggestion text isn't missing that space:

suggestion: Remove '-struct' for 'func myFunction(with one: Int, and two: String) -> Bool'
                                ^
                                with this change there is an added space here

[d-ronnqvist]

@swift-ci please test

[d-ronnqvist]

@swift-ci please test

[d-ronnqvist]

I started updating the user facing documentation related to link disambiguation but found that I want to make slightly larger documentation changes that I first thought and I feel that those updates would benefit from a separate review.

I will merge this PR now since it's a big improvement and there doesn't seem to be any major feedback anymore. If there's more changes that you're like to request, please message me and I'll make a follow up PR. I already have further refinements and enhancements in mind so I plan to continue to iterate on this code over the coming months anyway.