Improve heuristic for extending return value with "on failure" info

[d-ronnqvist]

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

Summary

This improves the heuristic for when DocC extends authored return value documentation with "On failure, ..." information for Objective-C API that corresponds to Swift API that throws errors.

Dependencies

None.

Testing

• In a mixed Swift and Objective-C project, add a Swift method that returns a value and throws errors.

  @objc
  func doSomething(with someValue: String) throws -> String { someValue }
  

• Give a basic description of the return value.

  /// Returns: Some value.
  

• Preview the documentation and navigate to the Objective-C representation of that method.

  • The return value documentation should include: "On failure, this method returns nil."

• Rephrase the return value documentation to something like:

  • "Some value. If an error occurs, this function doesn't return a value."
  • "Some value. On failure, this function doesn't return a value."
  • "Some value. If doing something fails, this function doesn't return a value."
  • "Some value. If something unexpected happens, this function returns nil instead."
  • "Some value, or nil if something goes wrong."

• Preview the documentation again and navigate to the Objective-C representation of that method.

  • The return value documentation shouldn't include: "On failure, this method returns nil."

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

[anferbui]

Overall it's looking good, there's some small typos and I've got a question on the implementation of the pattern matching.

[d-ronnqvist]

@swift-ci please test

The requested changes have been made

[d-ronnqvist]

@swift-ci please test

[anferbui]

The documentation looks great.

I left a comment about using Regex instead of NSRegularExpression, but I don't think that should block merge if you don't think it's relevant.

[anferbui]

Can we use Regex instead? It has an option for case insensitivity as well 1.

[d-ronnqvist]

Regex is available as of macOS 13 and we currently support macOS 12 (bumped very recently).

We probably could bump to macOS 13 but I didn't do that for this fix because this regular expression wasn't all that complicated.

[d-ronnqvist]

I left a comment about using Regex instead of NSRegularExpression, but I don't think that should block merge if you don't think it's relevant.

I think it's relevant and it would make the code more readable but it would require bumping the supported platform versions.

Still, I think that it's a topic that's worth revisiting in a separate PR. Then we could update all the regular expressions at the same time.