Swiftでのドキュメントコメントの書き方を覚えよう！
先日、jazzy: リファレンス自動生成ツールの記事を書きました。
その中で幾つかのドキュメントコメントの書き方を紹介しましたが、改めて説明しておきたいと思います。
Swiftではドキュメントコメントの中でマークアップ言語の書式が有効に働きます。
代表的なマークアップ言語の書式は下記の通りです。
マークアップ言語の書式
見出し
1
2
3
4
5
6
| # 最大見出し
## 大見出し
### 中見出し
#### 見出し
##### 小見出し
###### 最小見出し
|
リスト
1
2
3
4
5
6
| - リスト項目１
- リスト小項目１
- リスト小項目２
- リスト小項目３
- リスト項目２
- リスト項目３
|
順序リスト
1
2
3
4
5
6
| 1. 順序リスト項目１
1. 小順序リスト項目１
2. 小順序リスト項目２
3. 小順序リスト項目３
2. 順序リスト項目２
3. 順序リスト項目３
|
ItalicとBold
1
2
3
4
5
| normal
*Italic*
**Bold**
|
URLリンク
1
| [URLリンク](https://developer.apple.com/jp/)
|
罫線
1
2
3
4
5
6
7
8
| abcdefg
***
123456
---
あいうえお
___
かきくけこ
|
コード表記
(Octopressの都合上、ここでは書き方が異なりますが、ご了承ください。)
` ` `
self.sampleMethod()
` ` `
Swiftのドキュメントコメントの書式
MARK
1
2
3
4
5
6
7
| // MARK: - Properties
var sample:String = "sampleProperty"
// MARK: - Method
func sampleMethod() {
print("This is sampleMethod.")
}
|
FIXME
1
2
3
4
| func sampleMethod() {
// FIXME: - ログ出力ではなく、アラートを出す
print("This is sampleMethod.")
}
|
TODO
1
2
3
4
| func sampleMethod() {
// TODO: - ログ出力ではなく、何か処理を書く(まだ決まっていないけど)
print("This is sampleMethod.")
}
|
Parameter / Throws / Returns
1
2
3
4
5
6
7
8
9
10
11
| /**
サンプルメソッド
- parameter name: パラメータの書き方
- throws: 例外処理の書き方
- returns: 戻り値の書き方
*/
func sampleMethod2(name:String) throws -> String {
return "result: " + name
}
|
Description内で利用可能な文言
この他にクラス, プロパティ, メソッドの説明(Description)を書く際に利用可能な予約語的なものが幾つかあります。
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
| /**
- Attention: 注意書き
- Author: 作成者が一人の場合
- Authors: 作成者が複数人の場合
- Bug: バグの詳細
- Copyright: 著作権の所在
- Date: 日付(作成日, 更新日など)
- Experiment: 実験内容
- Important: 重要事項
- Invariant: 不変事項
- Note: その他、必要事項
- Precondition: 事前条件
- Postcondition: 事後条件
- Remark: 備考
- Requires: 要求事項
- SeeAlso: 参照事項
- Since: いつから実装されているか
- Version: バージョン
- Warning: 警告
*/
|
上記のように書くことで、 太字 かつ 各用語に属する説明 が付与されます。
まとめ
さて、いかがだったでしょうか？
これだけ知っていれば、ほぼ確実に困ることはないと思います。
どこまで頑張って書くかは開発者次第かもしれませんが、やはり初めてコードを見る人でも極力伝わるようにしておくことは必要不可欠かと思います。
といったところで本日はここまで。