XcodeでSwiftのコードヒントを正しく表示させる方法

ActionScript 3.0やJavaScriptといった言語のエディターには、変数や関数の宣言前に記述したコメントをコードヒントとして表示する機能があります。SwiftをプログラミングするためのIDE「 Xcode」にもこのような機能がありますが、コメントを正しく記述しないとコードヒントが表示されません。

コードヒントが表示される書き方

以下のコードをご覧ください。Hogeクラスには、2つの引数を加算するcalcSum()メソッドが定義されています。

Swift

class Hoge {
    
    init() {
        calcSum(1, b: 2);
    }
    
    /**
     aとbの合計を計算する
     - parameter a:値1
     - parameter b:値2
     - returns: aとbの合計
     */
    func calcSum(a:Int, b:Int) -> Int {
        let sum:Int = a + b;
        return sum;
    }
}

calcSum()メソッド前のコメントを見るとわかるように、**引数は@paramではなく「- parameter 」、戻り値は@returnではなく「returns:」**というキーワードで記述されています。

コードヒントの表示方法

コード補完時の表示

関数のコード補完時に、関数名の下に説明文が表示されます。引数や戻り値は表示されません。

Quick Helpでの表示

calcSum()を実行している箇所で、[alt]を押しながらクリックすると、下図①の箇所と②（Quick Help）の箇所にコードヒントが表示されます。また、[alt]を押さずにクリックすると、②のQuick Helpのみが表示されます。
それぞれの場所に以下の内容が表示されています。
Description：関数の説明
Parameters：引数の説明
Returns：戻り値の説明

コードヒントが正しく表示されない書き方

それでは、誤った書き方をするとどうなるのでしょうか？例えば以下のような記述をしてみます。

Swift

    /**
    aとbの合計を計算する

    @param a:値1
    @param b:値2
    @returns: aとbの合計
    */

Quick Helpを見ると、引数や戻り値の説明がDescriptionにまとめられ、引数や戻り値の説明がないのがわかります。

プラグイン「VVDocumenter-Xcode」を使うと記述が楽に

上記の記述を手動で行うのが面倒ならば、「VVDocumenter-Xcode」を使うと便利です。「///」と入力するだけで自動で記述できます。
インストール方法等は下記記事を参照するとよいでしょう。記事内で紹介されている記述は古いですが、VVDocumenter-Xcodeは最新の記述方法に対応していますのでご安心ください。
VVDocumenter-Xcode で Swift プロジェクトの API ドキュメントを記述する ｜ Developers.IO

最後に

少々記法は特殊ですが、慣れてしまえば他の言語と同じくコードヒントの恩恵に預かることができます。コードヒントを駆使して、規模の大きなプロジェクト開発も安全に進めていきましょう。

参考：Swift Documentation