Swift Markup: Callback argument breaks documentation string

Question

I am using Swift Markup Language to document class methods. Everything goes OK, but, here is a subtle issue.

Below goes a list of examples to explain what I am asking about.

1) Everything looks fine

/// My Fancy Method.
///
/// - Parameter number: A number.
/// - Parameter flag: A flag.
func methodWithoutCallback(integer number: Int, boolean flag: Bool) {

}

2) Still doing well

/// A method with callback (no arguments).
///
/// - Parameter string: A string.
/// - Parameter callback: A callback without arguments.
func methodWithVoidCallback(string name: String, _ callback: () -> ()) {

}

3) Not exactly what I've expected

/// This time things go wrong...
///
/// - Parameter number: A number.
/// - Parameter callback: Why there is a box with "No description" below?
func methodWithIntCallback(floating number: Float, _ callback: (Int) -> ()) {

}

4) Using typealias removes that thing away

typealias Callback = (Int) -> ()
/// And, there is a way to repair, but need typealias
///
/// - Parameter number: A number.
/// - Parameter callback: A callback (no box below)
func methodWithTypealiasedIntCallback(floating number: Float, _ callback: Callback) {

}

Did anybody have this issue? Or is it a kind of expected behavior? The issue comes up while using Xcode 9.2 (9C40b) and Swift 4 (if it matters).

UPDATE: Seems to be a duplicate of this question. But I wanted to clarify then: there is no way to ignore that box altogether, right? Because here is what you're getting if using proposed approach:

/// So, the box is coming up.
func methodWithCallbackParameterAnnotated(_ callback: (_ value: Int) -> Int) {

}

Possible duplicate of https://stackoverflow.com/questions/38669725/how-do-you-document-the-parameters-of-a-functions-closure-parameter-in-swift-3. — Martin R, Feb 16 '18 at 10:15
@Sweeper Not sure when this thing was introduced, but it is the first time I've spotted such behavior. — devforfu, Feb 17 '18 at 12:04
Swift 5 & Xcode 10: I've just come across this with an `@escaping` block: I gave it a "_ name" and a description and it still displays the whole thing in the extra boxes. Why is it doing that and how do you make it behave like a normal parameter? — Neph, Jun 13 '19 at 09:49

score 0 · Answer 1 · answered Oct 29 '19 at 15:45

You would need to define all parameters in the callback as well, at the same indentation level

/**
The box now has a description

- Parameters:
  - callback: (Int) -> Int, I just like to define the type of callback here
  - value: Here is where you describe the value param of the callback

*/
func methodWithCallbackParameterAnnotated(callback: (_ value: Int) -> Int) {

}

Swift Markup: Callback argument breaks documentation string

1 Answers1