Swift Markup：回调参数打破了文档字符串

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 （如果重要）时会出现此问题。

  

更新：似乎是this question的副本。但我想澄清一下：没有办法完全忽略那个盒子，对吧？因为如果使用提议的方法，这就是你所得到的：

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

}