コメントは大事

例えばこんな感じで書くと色々と便利。メソッドだけじゃなくてプロパティとかただの変数でもいい。

/**
 @method increment:
 @param i NSInteger 数値
 @return 引数iをインクリメントして返す
 
 引数iをインクリメントして返すお仕事
 */
- (NSInteger)increment:(NSInteger)i {
    return ++i;
}

気をつけること

1. コメントは/*!ではなく/**で始めた方がいい。Swiftで/*!が無視された(今は違うかも？
2. 説明を書くときは空行を入れる、もしくは@discussionを使う

この2つくらい。

使い方

コメントを書いたメソッドをクイックヘルプ(オプション+左クリック、もしくはコントロール+コマンド+ハテナ)するとこうなる(メソッドを呼び出す箇所でも同じ)。

しかしここまで書くのはめんどくさいし、そもそもクイックヘルプを表示するとかダルい。
どうせならメソッド打つときの補完と同じように大事な部分だけ表示できれば十分。

そんなときはこうする

voidメソッド

@returnだけ書く

/**
 @return 引数iをインクリメントして返す
 */
- (NSInteger)increment:(NSInteger)i {
    return ++i;
}

こうなる。おわかりいただけるだろうか、補完の候補としてでてきていながらも表示されるコメント。これはいいものだ。

non-voidメソッド

返り値がないので、@briefを書く。@returnとほぼ同じっていうか、@returnが@briefに[Returns]ってprefixついただけっぽい。

/**
 @brief 引数iをインクリメントする
 */
- (void)increment:(NSInteger)i {
    ++i;
}

補足

@returnと@briefを一緒に書くと@briefが優先されるので、その場合は@returnはクイックヘルプくらいでしか出番がなくなる。

参考 http://stackoverflow.com/questions/19168423/what-are-the-new-documentation-commands-available-in-xcode-5