Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[SymbolGraphGen] Include explicitly unnamed parameter names in function signature #77222

Open
wants to merge 1 commit into
base: main
Choose a base branch
from

Conversation

d-ronnqvist
Copy link
Contributor

This updated the "functionSignature" data to include explicitly unnamed parameter names.

For example, consider this Swift function:

func doSomething(_: Int, external _: Int) {}

Today, SymbolGraphGen emits the following signature information:

"functionSignature": {
  "parameters": [
    {
      "name": "",
      "declarationFragments": [ ... ]
    },
    {
      "name": "external",
      "declarationFragments": [ ... ]
    }
  ]
}

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:

"functionSignature": {
  "parameters": [
    {
      "name": "_",
      "declarationFragments": [ ... ]
    },
    {
      "name": "external",
      "internalName": "_",
      "declarationFragments": [ ... ]
    }
  ]
}

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.

/// - Parameter _: Some documentation for the unnamed (and unused) 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:

  • "with" (starts(with possiblePrefix:))
  • "at" (remove(at index:))
  • "for" (sleep(for duration:))
  • "by" (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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

1 participant