Takahiro Octopress Blog

-1から始める情弱プログラミング

Swiftでドキュメントコメントを正しく書こう!

| Comments

Swiftでのドキュメントコメントの書き方を覚えよう!

先日、jazzy: リファレンス自動生成ツールの記事を書きました。
その中で幾つかのドキュメントコメントの書き方を紹介しましたが、改めて説明しておきたいと思います。

Swiftではドキュメントコメントの中でマークアップ言語の書式が有効に働きます。
代表的なマークアップ言語の書式は下記の通りです。

マークアップ言語の書式

見出し
1
2
3
4
5
6
# 最大見出し
## 大見出し
### 中見出し
#### 見出し
##### 小見出し
###### 最小見出し

見出しを書いた場合

リスト
1
2
3
4
5
6
- リスト項目1
    - リスト小項目1
    - リスト小項目2
    - リスト小項目3
- リスト項目2
- リスト項目3

リストを書いた場合

順序リスト
1
2
3
4
5
6
1. 順序リスト項目1
    1. 小順序リスト項目1
    2. 小順序リスト項目2
    3. 小順序リスト項目3
2. 順序リスト項目2
3. 順序リスト項目3

順序リストを書いた場合

ItalicとBold
1
2
3
4
5
normal

*Italic*

**Bold**

ItalicとBold

URLリンク
1
[URLリンク](https://developer.apple.com/jp/)

URLリンク

罫線
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.")
}

MARK

FIXME
1
2
3
4
func sampleMethod() {
  // FIXME: - ログ出力ではなく、アラートを出す
  print("This is sampleMethod.")
}

FIXME

TODO
1
2
3
4
func sampleMethod() {
  // TODO: - ログ出力ではなく、何か処理を書く(まだ決まっていないけど)
  print("This is sampleMethod.")
}

TODO

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
}

Parameter / Throws / Returns

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: 警告                  
*/

上記のように書くことで、 太字 かつ 各用語に属する説明 が付与されます。

予約語1

予約語2

まとめ

さて、いかがだったでしょうか?
これだけ知っていれば、ほぼ確実に困ることはないと思います。
どこまで頑張って書くかは開発者次第かもしれませんが、やはり初めてコードを見る人でも極力伝わるようにしておくことは必要不可欠かと思います。

といったところで本日はここまで。

Comments