Support documenting platform specific properties and return values

[d-ronnqvist]

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

Summary

This fixes a special case with the validation of parameter and return value documentation where different platforms have different signatures for the language representation of the same symbol.

Dependencies

None.

Testing

• Define a C function with different parameters for different platforms, for example:

  #if TARGET_OS_OSX
  void doSomething(int first);
  #else
  int doSomething(int first, int second);
  #endif

• Extract symbol graph files for both platforms

• Document the function in a documentation extension file:

  # ``doSomething``
  
  Some documentation for this function
  
  - Parameters:
    - first: Some description for the parameter that's available on all platforms.
    - second: Some description for the parameter that's available on some platforms.
  - Returns: Some description for the return value that's only available on some platforms.

• Build documentation using both platform's symbol graph files.

  • There shouldn't be a warning about the documentation for the second parameter or the return value.
  • The rendered page should display both parameter's documentation and the return value documentation.

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 Not applicable

[anferbui]

@d-ronnqvist Could you please share a screenshot of the rendered page for the example symbol from your PR description?

[d-ronnqvist]

@d-ronnqvist Could you please share a screenshot of the rendered page for the example symbol from your PR description?

Absolutely. I added a screenshot. It's not particularly exciting; just both declarations and both parameter's documentation (and the return value documentation).

Without these changes it would non-deterministically (depending on which symbol graph file it loaded first) display either the return value documentation (which applies to one platform) or the second parameter's documentation (which only applies to the other platform).

[anferbui]

LGTM with minor comments :)

Thanks for the screenshot, that helped me understand the changes!

[anferbui]

I think this if statement is not needed because if there's no difference then the array will be empty and the loop will iterate over nothing (which is the desired behaviour)

Suggested change

	if !existing.parameters.elementsEqual(signature.parameters, by: hasSameNames) {
	for case .insert(offset: let offset, element: let element, _) in signature.parameters.difference(from: existing.parameters, by: hasSameNames) {
	existing.parameters.insert(element, at: offset)
	}
	}
	for case .insert(offset: let offset, element: let element, _) in signature.parameters.difference(from: existing.parameters, by: hasSameNames) {
	existing.parameters.insert(element, at: offset)
	}

[d-ronnqvist]

The extra if-statement isn't necessary but it's faster in the common case where the API has the same signature on all platforms.

Here's a chart (that I made just now) of a microbenchmark where I create 1000 fake symbols, that each exist on two platforms and have an increasing number of fake parameters named "AAAAAAA", "BBBBBBB", "CCCCCCC", etc. on both platforms.

You can see that the equalElements(_:by:) check makes a fairly fast early exit compared to much more sophisticated differences(from:by) computation that finds no differences. As the symbols get more and more parameters this difference is lessened but at fewer than 10 parameters, it's a rather significant difference.

If I update the benchmark to have minor differences between the parameters of each platform for all 1000 fake symbols, the overhead of the redundant equalElements(_:by:) check is barely measurable:

[d-ronnqvist]

I'll add a shorter version of this comment to the code so that someone else (including me when I inevitably forget about this) doesn't remove the if-statement in the future.

[anferbui]

Thank you for the deep-dive, sounds great!

[d-ronnqvist]

@swift-ci please test