[SymbolGraphGen] Include explicitly unnamed parameter names in function signature #77222
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
This updated the "functionSignature" data to include explicitly unnamed parameter names.
For example, consider this Swift function:
Today, SymbolGraphGen emits the following signature information:
The empty string for the first parameter causes issues for DocC when it tries to associate parameter documentation with the parameter. I could imagine other tools that process documentation would face the similar issues with this information.
With the changes in this PR, SymbolGraphGen would instead emit this the following signature information:
I think this is a clear benefit for the first parameter in the example above (
_: Int
) because it allows developers to write documentation for it like below and allows tools that process the function signature information to associate that documentation with that parameter.That said, I'm a bit torn about what's there best way to emit the parameter names for the second parameter.
It might make more sense for the developer to reference that parameter by its argument label (external name) rather than its parameter name (internal name).
Parameter names are generally preferred over arguments labels in Swift documentation because they are unique and because Swift's API design guidelines sometime lead to argument labels that serve as a prepositional phrase, for example:
starts(with possiblePrefix:)
)remove(at index:)
)sleep(for duration:)
)sorted(by areInIncreasingOrder:)
However, it's allowed to use "" for multiple parameters (as shown above) which removes the uniqueness benefit and "" isn't any more descriptive than "with", "at", "for", or "using" would be.
Resolves rdar://138630917