[SR-4805] Provide an @available argument for recommendations

[tonyarnold]

Previous ID	SR-4805
Radar	None
Original Reporter	@tonyarnold
Type	New Feature

Attachment: Download

Additional Detail from JIRA

| | | |------------------|-----------------| |Votes | 0 | |Component/s | Compiler | |Labels | New Feature | |Assignee | None | |Priority | Medium | md5: 3bd06f4e8c6fec9d07e3f8729d9e7032

Issue Description:

There's an override in Swift master right now that's marking a specific override of the flatMap(…) function as deprecated:

  @available(*, deprecated, message: "This call uses implicit promotion to optional. Please use map instead.")
  public func flatMap<T>(
    _ transform: (${GElement}) throws -> T
  ) rethrows -> [T] {
    return try map(transform)
  }
}

This produces a warning to the user that indicates the function is deprecated, however the actual intent here seems to be to make a recommendation that this isn't the most efficient method of handling this scenario.

For me, this was a confusing message to receive (it took a conversation on Twitter to determine that this function is not actually deprecated).

It seems to me that there is a need for another attribute argument here - something akin to:

@available(*, recommendation, message: "This call uses implicit promotion to optional. Please use map instead.")

// OR

@available(*, inadvertent, message: "This call uses implicit promotion to optional. Please use map instead.")

That would present the user with a warning, sans the deprecation information (and in this case, should also offer a fix-it. I digress).

The alternative answer could be that this function should actually be marked as obsolete or unavailable - assuming there's no situation where it's the right answer, because there's no way to suppress the warning these availability annotations produce.

[belkadan]

I'm not sure it's worth treating this as any different from a deprecation. It's something you should fix before you ship, but you don't have to fix it now.

[tonyarnold]

Perhaps I'm being a pedant about semantics here 😃