Document how to disambiguate symbol links using type signature information

[d-ronnqvist]

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

Summary

This adds user facing documentation about disambiguating symbol links using type signature information, added in #643 and #1087

At first I tried to insert a section about type signature into the existing documentation structure but I found that the current order made the documentation hard to follow. Specifically, these two changes made the flow of the documentation somewhat confusing:

• Examples about unambiguous symbol links were both before and after the examples about ambiguous symbol links. With even more examples about ambiguous links, this made it hard to know where to insert the new examples.
• Disambiguation using hashes was explained before disambiguation using symbol types. This made it hard to know where to insert the explanation about type signature disambiguation.

So, before adding new documentation I addressed some of the issues with the flow of the existing documentation:

• Adding more documentation, with examples, about how relative symbol links work.
• Moving all examples of unambiguous symbol links before any examples of ambiguous symbol links and creating a dedicated subsection about link disambiguation.
• Move the example about symbol kind disambiguation before the example about hash disambiguation so that there's a clear flow from simpler and more readable disambiguation to the unreadable hash disambiguation.
• Add a handful of missing symbol type to the list of supported symbol type disambiguation values.

With those changes done, it felt more natural to:

• First update the Sloth/update(_:) to give a basic description of type signature disambiguation
• Then add a more advanced example with mixed parameter type and return values disambiguation.

Dependencies

None.

Testing

Read the new documentation.

Checklist

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

• [ ] Added tests This only changes documentation.
• Ran the ./bin/test script and it succeeded
• Updated documentation if necessary

[heckj]

Looks great David. Kind of jealous of the text-graphics skill in some of those examples. And hugely looking forward to this capability in 6.1+, the symbols are hugely easier to understand while writing!

[mayaepps]

This looks great! 🎉

[mayaepps]

If it doesn't disambiguate the link, why would someone use this suffix?

[d-ronnqvist]

In the first few releases of DocC (before Xcode 14.3) DocC required the language identifier prefix for unrelated and uninteresting implementation detail reasons, even though the that information wasn't useful for disambiguation purposes. Links created during those releases continue to work but can be shortened.

[d-ronnqvist]

@swift-ci please test