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.

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

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?

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.