【Xcode】ドキュメントコメントについて知ってる事全てまとめてみた

# 概要
みなさん、Xcodeでコメント、ドキュメントどうしてますか？
Xcodeは結構コメントのドキュメント化に対応しているので今回はそれについてまとめてみようと思います。
見方、書き方の順でまとめています。
今までより少しでも皆さんのコードが分かりやすいものになれば幸いです。

# 筆者環境
| Item | Version |
|:------|:------:|
| Xcode | 11.4 |
| Swift |  5.2 |

# ドキュメントコメントの見方

みなさんが書いたコメントがどこにどの様に表示されるかをまとめていきます。

## コード書いてる途中

```swift:GreatestEnum.swift
/// 1行目
/// 2行目
/// 3行目
enum GreatestEnum {

}
```
<img width="383" alt="スクリーンショット 2020-04-11 16.51.08.png" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/11800/a9be9f0b-e931-cbbc-ee9e-8e6fd875a05e.png">

コメントが複数行でも、一行になって表示されます。
また、後に表記するMarkdown形式には対応していません。
長すぎると、「...」で省略されます。

## option押しながらクリック

optionを押しながらクラス名などをクリックするとポップアップが出てきて表示されます。

```swift:GreatestEnum.swift
/**
 1行目
   2行目(インデントは無視される)
 
 2行開けるとここからはDiscussionになります。

 ここは同じくDiscussionになります。
 */
enum GreatestEnum {

}
```

<img width="505" alt="スクリーンショット 2020-04-11 16.56.22.png" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/11800/3e486cde-ea63-1679-154d-ec6915ee592a.png">

基本的に後に記す書き方の全てに対応しています。

## QuickHelpインスペクタ

[View] - [Inspectors] - [Show Quick Help Inspector]
または
option + ⌘ + 3

で出てくるインスペクタに表示されます。

```swift:GreatestEnum.swift
/**
 1行目
   2行目(インデントは無視される)
 
 2行開けるとここからはDiscussionになります。

 ここは同じくDiscussionになります。
 */
enum GreatestEnum {

}
```

<img width="260" alt="スクリーンショット 2020-04-11 16.57.52.png" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/11800/95396737-e102-e5f7-bd39-e2d6e635f88b.png">

## Document Items

[View] - [Editor] - [Show Document Items]にも一部コメントが表示されます。

```swift:Test.swift
class Test {
  func someFunc() {
    // MARK: - hoge -
    // TODO: - hoge - 
    // FIXME: - hoge -
  }
}
``` 

それぞれドキュメントアイテムにアイコン付きで表示されます。
前後空白付きで-を記述すると水平線が引けます。
今書いてて気付いたんですが、MARKとTODOって微妙にアイコン違うんですね笑

<img width="359" alt="スクリーンショット 2020-04-11 17.38.03.png" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/11800/beece611-bf0a-1d0c-e9e7-aa7d2d8dc75f.png">

## Minimap

Xcode11から導入されたミニマップですが、ここにも一部記述が表示されます。

```swift:Minimap.swift
// MARK: Shown to Minimap
class Test {

}
```

<img width="142" alt="スクリーンショット 2020-04-11 18.00.53.png" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/11800/8b30591a-80f1-b307-d33b-9dcdbaf20da6.png">

// TODO: や // FIXME: は表示されません。
また、これら3つは///で表記してしまうと機能しません。

# ドキュメントコメントの書き方

では、次に何をどの様に書けるのか見ていきましょう。

## どの様に書くのか

### 基本編
コメントの書き方には大きく分けて3種類あります。

#### 通常コメント
多分一番多く使われているコメントの形式だと思います。

```swift:
// コメント
```

こちらの形式は先ほど述べたTODOなど以外では外部に露出する事はありません。

#### ドキュメントコメント

```swift:
/// コメント
```

```swift:
/**
  コメントコメント
 */
```

XcodeのThemeにもよるのかもしれませんが多分カラーリングが変わるかと思います。

こちら二つでドキュメントコメントは書きます。

### 関数コメント

関数にカーソルを合わせた状態で 「option + ⌘ + /」で関数のコメントが追加されます。

```swift:Function.swift
/// <#Description#>
/// - Parameters:
///   - application: <#application description#>
///   - launchOptions: <#launchOptions description#>
/// - Returns: <#description#>
func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {

}
```

![document_comment.gif](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/11800/fcb6974f-d5b5-5503-4c0b-c9c352381310.gif)

・パラメータ

```
/// - parameter [パラメタ名]: [説明]
```

または

```
- Parameters:
  - [パラメタ名]: [説明]
  - [パラメタ名]: [説明]
```

・戻り値

```
- Returns: [説明]
```

の形式で記述します。

### 応用編

#### Markdown

コメントは一部Markdown方式に対応しています。

```swift:markdown.swift
/// *italic*
/// **bold**
/// *** (平行線)
/// # paragraph
/// ## #と特に違いはない様な？
/// ### #と特に違いはない様な？
/// [リンク](https://google.com)
/// 1. one
/// 2. two
/// 3. three
/// - one
/// - two
/// - three
/// ```
/// let TestClass = TestClass()
/// ```
/// ~~~
/// let TestClass = TestClass()
/// ~~~
```

<img width="259" alt="スクリーンショット 2020-04-11 18.16.25.png" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/11800/48541fcc-d737-19c8-46f1-865fd8c39de5.png">

https://www.egao-inc.co.jp/programming/swift_documentcomment/
この記事なんかをみると昔は#や##の違いはあったのかもしれないですね。

個人的には **``` や ~~~ でcode blockが追加出来る**のは良い発見でした。

### 特殊フィールド

なんと命名すれば良いか分からないのですが、
これ以外に予め設定されたキーワードをハイフン付きで記入すると
特別なセクションが出来上がります。

```swift:Field.swift
/// - Precondition
/// 前提条件
/// - Postcondition
/// 事後条件
/// - Requires
/// 必要条件
/// - Invariant
/// 不変
/// - Complexity
/// 複雑度
/// - Important
/// 重要
/// - Warning
/// 警告
/// - Author
/// 著者
/// - Authors
/// 著者複数
/// - Copyright
/// コピーらいと
/// - Date
/// 日付
/// - SeeAlso
/// これもみてね
/// - Since
/// いつから
/// - Version
/// バージョン
/// - Attention
/// 注意
/// - Bug
/// バグ
/// - Experiment
/// 実験
/// - Note
/// ノート
/// - Remark
/// 気付き
/// - ToDo
/// TODO
```

<img width="262" alt="スクリーンショット 2020-04-11 18.17.23.png" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/11800/c24182e6-3251-ac82-e2df-22f27ddfda39.png">

## どこに書くのか

最後に、どこに書けるのかをまとめます。
基本的に、上記の書き方は下記に記す位置どこにでも書けるかと思います。

### 列挙型

```swift:TestEnum.swift
/// enumのコメント
enum TestEnum {
  /// caseのコメント
  case hoge
  /// case毎に書ける
  case fuga

  /// funcのコメント
  func someFunc() {
    // 何か
  }
}
```

### class, struct

```swift:TestClass.swift
/// classのコメント
class TestClass {
  /// private varのコメント
  private var privateVar = 0

  /// internal varのコメント
  var internalVar = 0

  /// funcのコメント
  func someFunc() {
    // 何か
  }
}
```

もし、こんなのもあるよ！とかここ書き方違うよ！とか
あればコメントで教えてもらえると嬉しいです。

誰かのお役に立てば。

# 参考
https://qiita.com/Todate/items/819618dbb56e61d97453
https://nshipster.com/swift-documentation/
https://qiita.com/hironytic/items/12589b4735f4c95eec0c