Swift 2のドキュメントコメントの書き方（JavaDoc的なやつ）

コード補完時やoptionクリック時などに説明が出てくるようにする「ドキュメントコメント（Javaで言うJavaDocみたいなやつ）」の書き方について解説したいと思います！

ドキュメントコメント（文書化コメント）

/** から始まるコメント、または /// で始まる行末までのコメントがドキュメントコメント（文書化コメント）として扱われます。

/**
 コメント
 */

/// コメント

段落

空白行によって段落を表現できます。

段落1

段落2

段落3

ソースコード

行の先頭に空白4つ、あるいは前後行を「“`（バッククォート3つ）」で囲うとコード行としてグレーの四角で囲われます。

``` 
let b = 234 
```

引数

以下のいずれかの書式で、引数に関する情報を書くことができます。

- parameter 引数1: 引数1に関する説明
- parameter 引数2: 引数2に関する説明

- parameters:
    - 引数1: 引数1に関する説明
    - 引数2: 引数2に関する説明

返り値

以下の様な書式で、返り値に関する情報を書くことができます。

- returns: 返り値に関する説明

エラー

以下の様な書式で、エラーがthrowされる場合の情報を書くことができます。

- throws: エラーがthrowされる場合の説明

見出し

行の先頭に#を置くことで、その行を見出しにできます。

# 見出し1

## 見出し2

### 見出し3

箇条書き

“-“, “+”, “*” を使うと箇条書きを表現できます。

- 項目1
- 項目2
- 項目3

太字・斜体

「**文字列**」「__文字列__」を使うと太字、「*文字列*」「_文字列_」を使うと斜体を表現できます。

**太字**

*斜体*

水平線

「—」または「***」で水平線を表現できます。

---

***

リンク

[リンク文字列](リンク先のアドレス) で、リンクを表現することができます。

[卵は世界である](https://eggisworld.thick.jp)

実例

ドキュメントコメントを使った実例を以下に示します。

/// 割り算に関するエラー
enum DivideError : ErrorType {
    /// ゼロ除算
    case ZeroDivide
}


/**
 割り算を行う
 
 - parameter num1: 割られる数
 - parameter num2: 割る数
 
 - throws: 割る数が0だった場合にエラー
 
 - returns: 割り算の結果
 */
func divide(num1 num1: Int, num2: Int) throws -> Int {
    guard num2 != 0 else {
        throw DivideError.ZeroDivide
    }
    
    return num1 / num2
}

@akio0911はこう思った。

ドキュメントコメントをキッチリ入れておくと、コード補完時などに説明が出てくるのでコードが書きやすく＆読みやすくなると思います！

ちなみにSwift 2のコメントに関しては以下の書籍に詳しく載っているので、気になる方は読んでみると良いかもです。

Swift 2標準ガイドブック　【Swift 2.1対応版】[Kindle版]

posted with ヨメレバ

渡辺 龍司,富家 将己,鈴木 晃,加藤 寛人 マイナビ出版 2015-10-23

Kindle

Amazon[書籍版]

詳解 Swift 改訂版

posted with ヨメレバ

荻原 剛志 SBクリエイティブ 2015-12-25

Amazon

Kindle

楽天ブックス