Swift 2 で強化されたコメント表記をまとめた #1では、Line formmatingについて書きました。
今回はSymbol Sectionについて書きます。
Symbol Sectionは、メソッドのパラメータや戻り値を書くためのフォーマットです。
ちなみに、Symbol Sectionは、VVDocumenter-XcodeというXcodeのプラグインを使うと簡単に記述できるのでおすすめです。
ここにドキュメントがあります。
基本的なフォーマット
パラメータ
「- parameter パラメータ名: 詳細」というフォーマットで1つずつ記載します。
複数のパラメータがある場合には、
「- parameters:」を書き、次の行に「- パラメータ名: 詳細」で記載することもできます。
/**
- parameter パラメータ名1: 詳細
- parameter パラメータ名2: 詳細
*/
複数のパラメータがある場合には以下の書き方も可能
/**
- parameters:
- パラメータ名1: 詳細
- パラメータ名2: 詳細
*/
戻り値
戻り値は、「- returns: 詳細」で記載できます。
/**
- returns: 戻り値詳細
*/
エラーハンドリング
エラーを返す可能性があるメソッドの場合、投げるエラーの詳細を書けます。
書式は「- throws : 詳細」です。
/**
- throws: 詳細
*/
表示例
補助表示コマンド
メソッドの詳細部分には細かい記述をするためのシンボルが用意されています。
基本的な記述方法は、「- シンボル名: 詳細」となります。
Authorsのみ記述方法が違いますが、ここでは触れません。
| シンボル | 内容 |
|---|---|
| attention | 注意事項 |
| author | 作成者 |
| authors | 作成者(複数) |
| bug | バグ |
| complexity | 複雑さ |
| copyright | コピーライト |
| date | 日付 |
| experiment | 実験内容 |
| important | 重要事項 |
| invariant | 一定の内容 |
| note | ノート |
| precondition | 必要(前提)事項 |
| postcondition | 事後事項 |
| remark | 注目 |
| requires | 必要事項 |
| seealso | 関連項目 |
| since | 作成日 |
| todo | To Do |
| version | バージョン |
| warning | 警告事項 |
特殊なコメント
Objective-Cでよく使う、「#pragma mark」に相当するコメントも用意されています。
「MARK:」「TODO:」「FIXME:」です。
「#pragma mark -」と同様に、「MARK: -」でラインが挿入されます。
// MARK: -
// MARK: private methods
func sample() {
// TODO: 処理を書く
// FIXME: 修正する
}
表示例
ちょっと宣伝
著書「Swift 2 標準ガイドブック」には、このコメント記述方法についてもきちんと載ってます。
2015年11月24日まで特別価格になっていますので、細かい部分まで知りたい人は是非買ってみてください。