最近ポケモンGOにハマっているトクです。島根には殆どポケストップが無くて、常にモンスターボール不足な状況が続いていますが、それなりに楽しんでいます…。
さて今回は、「文書化コメント」について説明したいと思います。
文書化コメントとは、関数やメソッドの使い方を記述したコメントのことで、関数を使用する時に説明が見えるようにするためのものです。
クラスの使い方 等で print を記述されたかと思いますが、option キーを押しながらマウスカーソルを関数へ持っていくと「 ? 」マークが表示されます。この状態でクリックしたら下のようなバルーンが表示され、引数などを見ることができます。文書化コメントを使用することにより、自分で作成した関数にも同じように表示させることが出来るようになります。
使い方
/** から始まるコメント、または /// で始まる行末までのコメントが文書化コメントとして扱われます。
|
1 2 3 |
[sourcecode lang="swift"]/** コメント */[/sourcecode] |
|
1 |
[sourcecode lang="swift"]/// コメント[/sourcecode] |
一般的なもの
説明
関数の説明を記述できます。
|
1 2 3 4 5 |
[sourcecode lang="swift"]/** 説明 */ func comment0() { }[/sourcecode] |
引数
引数に関する情報を記述でき、書き方には二通りあります。
|
1 2 3 4 5 6 |
[sourcecode lang="swift"]/** - parameter パラメータ名1: 詳細 - parameter パラメータ名2: 詳細 */ func comment1(param1: Int, param2: Int) { }[/sourcecode] |
|
1 2 3 4 5 6 7 |
[sourcecode lang="swift"]/** - parameters: - パラメータ名1: 詳細 - パラメータ名2: 詳細 */ func comment1(param1: Int, param2: Int) { }[/sourcecode] |
戻り値
戻り値について記述できます。
|
1 2 3 4 5 6 |
[sourcecode lang="swift"]/** - returns: 戻り値詳細 */ func comment2() -> Int { return 0 }[/sourcecode] |
エラー
エラーが投げられる場合の説明を記述できます。
|
1 2 3 4 5 |
[sourcecode lang="swift"]/** - throws: エラーがthrowされる場合の説明 */ func comment3() { }[/sourcecode] |
その他
段落
空白改行で区切ります。
|
1 2 3 4 5 6 7 8 9 |
[sourcecode lang="swift"]/** 段落1 段落2 段落3 */ func comment4() { }[/sourcecode] |
ソースコードを引用
他の段落より空白４つ分右にインデント又は、バッククォート３つで挟んだ段落
|
1 2 3 4 5 6 7 8 |
[sourcecode lang="swift"]/** 説明 print("hello") */ func comment5() { }[/sourcecode] |
|
1 2 3 4 5 6 7 8 |
[sourcecode lang="swift"]/** 説明 ``` print("hello") ``` */ func comment5() { }[/sourcecode] |
実例
文書化コメントを使用した例
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 |
[sourcecode lang="swift"]enum BallType { case MonsterBall case SuperBall case HyperBall case MasterBall } /** 指定したIDのボケモンをゲットする - parameters: - id: ボケモンのID - ballType: モンスターボールのタイプ - returns: ゲットできたかどうか */ func bokemonGet(id: Int, ballType: BallType) -> Bool { return false }[/sourcecode] |
まとめ
文書化コメントを使用することにより、関数の使い方が分かりやすくなったかと思います。他にも便利な機能がありますので、調べて使用してみてください。
