クロージャの引数のコードヒントが表示されない。

次のような、引数のクロージャを実行するだけの特に意味のないファンクションの場合…

無意味な関数

func doSomething(index: Int, handler: (Int) -> Void) {
    handler(index)
}

⌥⌘ + / でコメントテンプレートを挿入して、次のように記述した場合に、

コメント例

/// クロージャを実行
///
/// - Parameters:
///   - index: 何らかの値
///   - handler: 実行するクロージャ

doSomething を ⌥+クリックすると次のようなコードヒントが表示されてしまう。

気になるのは | - | No description. | の部分。いろいろ調べた結果、不本意ながら、次のように記載することでクロージャの引数にもコメントが表示されるようになった。

修正後

/// クロージャを実行
///
/// - Parameters:
///   - index: 何らかの値
///   - handler: 実行するクロージャ
///   - i: クロージャが要求する何らかの値
func doSomething(index: Int, handler: (_ i: Int) -> Void) {
    handler(index)
}

ポイントは**「クロージャの引数の記述に名前をつけたこと」と「その名前にコメントを追加したこと」**の２点。

注意点

doSomething の引数である index と同じ名前の引数をクロージャの引数（上の例では i）につけて、コメントに -index: が二回出現させると後に書かれた方が優先されて、コードヒントでは両方に同じコメント（上の例では「クロージャが要求する何らかの値」）が表示されてしまいます。

悪い例

/// クロージャを実行
///
/// - Parameters:
///   - index: 何らかの値
///   - handler: 実行するクロージャ
///   - index: クロージャが要求する何らかの値
func doSomething(index: Int, handler: (_ index: Int) -> Void) {
    handler(index)
}

未解決問題

クロージャが戻り値を持つ場合の記述方法が解らない。

不満／不本意なところ

⌥⌘ + / で挿入されるテンプレートでクロージャの引数が考慮されていないこと（変更後の書き方でもテンプレートは同じだった）。
引数であるクロージャの引数には名前がつけられないのに「_ + 引数名」の形式で名前をつけていること。