[SR-3162] Generated ObjC header doc generate warnings when closure parameters are documented

[belkadan]

Previous ID	SR-3162
Radar	rdar://problem/29162619
Original Reporter	@belkadan
Type	Bug

Additional Detail from JIRA

Votes	0
Component/s	Compiler
Labels	Bug, PrintAsObjC, StarterBug
Assignee	None
Priority	Medium

md5: 78bb297fbc54491dc1e3f572b5cb816a

Issue Description:

Given this Swift definition:

    /// Writes to an output stream
    ///
    /// - Parameters:
    ///   - outputStream: The output stream to write to
    ///   - completionQueue: The completion queue to call your completion handler on. If `nil` the main queue is used.
    ///   - completion: A completion handler called after the data is written or an error is thrown.
    ///   - error: If successful this will be `nil`, otherwise contains the error thrown.
    public func writeTheThing(
        outputStream: OutputStream,
        completionQueue: DispatchQueue = DispatchQueue.main,
        completion: @escaping (_ error: Error?) -> Void) {}

This Objective-C definition is generated:

/**
  Writes to an output stream
  \param outputStream The output stream to write to

  \param completionQueue The completion queue to call your completion handler on. If \code
  nil
  \endcode the main queue is used.

  \param completion A completion handler called after the data is written or an error is thrown.

  \param error If successful this will be \code
  nil
  \endcode, otherwise contains the error thrown.

*/
- (void)writeTheThingWithOutputStream:(NSOutputStream * _Nonnull)outputStream completionQueue:(OS_dispatch_queue * _Nonnull)completionQueue completion:(void (^ _Nonnull)(NSError * _Nullable))completion;

The result is when the Project-Swift.h file is imported in Objective-C the “error” parameter generates a warning because it isn’t a valid parameter name in ObjC headerdoc comments.

[jtbandes]

Is this really a bug? error is not a parameter name of the Swift function either. I'm not aware of a way that headerdoc-style comments can formally represent a \param of another \param.

[belkadan]

I think it'd be fine to just drop them from the HeaderDoc. Better than including them and getting warnings.

[swift-ci]

Comment by John Szumski (JIRA)

HeaderDoc does support nested parameter documentation as seen in the test input comment_to_something_conversation.swift:

/// Partially applies a binary operator.
///
/// - Parameters:
///   - a: The left-hand side to partially apply.
///   - combine: A binary operator.
///     - Parameter lhs: The left-hand side of the operator
///     - Parameter rhs: The right-hand side of the operator
///     - Returns: A result.
///     - Throws: Nothing.
@objc public func closureParameterOutlineExploded(a: Int, combine: (_ lhs: Int, _ rhs: Int) -> Int) {}

@belkadan, do you want to keep your approach to simply drop top-level parameters or should we attempt to match them to an appropriate nested param if it exists?

[belkadan]

That doesn't look like valid HeaderDoc to me. I suspect Xcode is just being polite and using the Swift doc parser instead, or ignoring the section entirely. Pulling in @bitjammer.