Swiftでヘッダドキュメント

メソッドや関数のヘッダコメントに、その説明を書くのは JavaDoc 以前からよく行われていたドキュメンテーションの方法ですが、Swift では JavaDoc スタイルの記述方法がうまく働かなくなっていました。「@param」や「@return」が認識されないのです。

これ、「@param」ではなく「:param:」、「@return」ではなく「:returns:」だと認識してくれるみたいです。
(参考: http://nshipster.com/swift-documentation/ )
ただし、Description と :param: の行の間には空行を挟む必要があるようです。

また、リストも行頭に「-」または「+」をつければ、簡単にかけるようです。

コメントも「/**」「*/」で囲む方法ではなく、行頭に「///」でもよいようです。

追記:

番号付きリストや、定義リスト、ブロック引用も整形してくれるようです。

番号付きリストは、数字1文字とピリオドを行頭につければ 1 から始める必要はないようです。また、「#.」と書くこともできます。

定義リストは術語の次に空行を挟まずに定義を字下げして書きます。
術語を「:」で挟んだフィールドリストも書けます。定義リストに似ていますが、術語と同じ行から定義段落を始めることができます。
ブロック引用は、段落を字下げして書きます。字下げを深くしていくことでネストさせることができます。