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

  • 79
    いいね
  • 0
    コメント

(2015/11/07 追記)
Xcode 6向けの記事でしたが、Xcode 7から記法が変わったので修正しました。
(追記終わり)


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:」というキーワードで記述されています。

コードヒントの表示方法

コード補完時の表示

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

Quick Helpでの表示

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

Quick Help

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

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

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

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

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

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

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

最後に

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

参考:Swift Documentation