はじめに

Objective-Cでコードを書く時にはdoxygen形式でコメントを入れていた。
そうするとクラスやメソッドの概要などがXcodeのQuick Helpへ反映され、便利だなと思っていたのだが。
Swiftで同様にコメントを入れたところ、それがQuick Helpに反映されない・・・
ので、そのことについて調べてみた。


結論

Swiftではdoxygen形式でコメントを書いても、Quick Helpへは一部反映されない。
/3つで始まるコメントを使うと反映される。


どういうことなのか

doxygen形式でも、クラスやコメントのSummaryは正しく認識されるし、ツールを使ってドキュメントを吐き出すことも可能らしい。
しかし、

一行目にメソッドの説明と:param:、:return:を使えばとりあえず問題なし

との情報を見て試したが、:param:がDiscussionの欄に反映され、Parametersの欄にはNo descriptionと表示されてしまう。どうやらObjective-Cのソースのようには認識してくれないようだ。

Option+Command+/を押すと/3つから始まるコメントが自動生成され、この内容はQuick Helpに反映される。

/// <#Description#>
///
/// - Parameter param1: <#param1 description#>
/// - Returns: <#return value description#>

ショートカットですぐ定型のコメントが出るので、doxygen形式よりも便利だなと思った。
あと、Markdown形式で書けるのも良い。
今後Swiftではこの形式のコメントを使っていこうと思う。


参考にしたページ：