Swift 标记 : Callback argument breaks documentation string

Question

我正在使用 Swift Markup Language记录类方法。一切正常，但是，这里有一个微妙的问题。

下面列出了一些示例来解释我所问的问题。

1) 一切正常

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

}

2) 还不错

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

}

3) 不完全符合我的预期

/// 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) 使用 typealias 会删除那个东西

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) {

}

有人有这个问题吗？或者这是一种预期的行为？使用 时出现问题Xcode 9.2 (9C40b) 和 swift 4 (如果重要的话)。

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) {

}

Answer 1

您还需要在回调中定义所有参数，位于 相同的缩进级别

/**
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) {

}