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

---

UPDATE：似乎是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) {

}