Improve parsing of links with type disambiguation that include generics

[d-ronnqvist]

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

Summary

This fixes issues where certain type disambiguation spellings with generics in symbol links wouldn't match the corresponding symbol.

Dependencies

None

Testing

• Define two method overloads that differ by a generic parameter. For example:

  public struct Something {
      public func doSomething(_ keyPath: KeyPath<Something, Int>)    {}
      public func doSomething(_ keyPath: KeyPath<Something, String>) {}
  }

• Write an ambiguous link to these overloads. For example:

  /// An ambiguous link to ``doSomething(_:)``
  

• Build DocC's suggestion and accept one of the suggestions for how to disambiguate the link. For example:

  ``doSomething(_:)-(KeyPath<Something,Int>)``
  

• Build documentation again.

  • The link should resolve successfully to that overload.

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]

@swift-ci please test

[d-ronnqvist]

@swift-ci please test

[patshaughnessy]

Looks good!

[patshaughnessy]

Maybe add a doc comment with an example value, to make this code a bit easier to follow. Same throughout for scanArgument, scanTuple, etc.

We have the nice ascii-art diagrams above near the definition of parseTypeSignatureDisambiguation. Maybe just paste a piece of that for each of these utility functions?

[d-ronnqvist]

I added some documentation to the private scanner API—with examples that show the scanner's state—in 6a9718b

[d-ronnqvist]

@swift-ci please test