【Swift】ドキュメンテーションコメントで使える Symbol Command Syntax のキーワード【まとめ】

# はじめに

[API Design Guideline](https://swift.org/documentation/api-design-guidelines/)にて、ドキュメンテーションコメントについて触れられています。

> **Write a documentation comment** for every declaration.

(( ；ﾟДﾟ))


ということで、しっかりドキュメンテーションコメントを書くためにまとめてみました。

基本的には公式リファレンスをしっかり読んでもらえればこの記事を読む必要はないかと思います。笑

公式リファレンスをもとに書きましたが、解釈が間違えている箇所などあればご指摘ください。 :raised_hands: 


# Symbol Command Syntax とは？

**Symbol**は、クラスやメソッド、列挙型などを指します。

Symbolのドキュメンテーションコメントとして、**Symbol Command Syntax**という書き方で書くことができるようです。

ここでは、**Symbol Command Syntax**のキーワードの紹介に留めますので、
ドキュメンテーションコメントの詳しい書き方については触れません。

# キーワードの種類

キーワードの種類として`Section`と`Callout`の２種類があります。
それぞれについてまとめていこうと思います。

`Section`はドキュメンテーションコメントの大項目、`Callout`は補助的な項目というイメージです。

# Section

Sectionにあたるキーワードは、`Parameters`や`Returns`といった、クイックヘルプの左サイドの項目として表示されるものです。

## Section一覧

それでは、Sectionのキーワードを紹介します。例や画像はリファレンスのものになります。

### Parameter

- 種類：**section**
- 説明：パラメータの説明を書きます。複数のパラメータについて記述する場合は後述の`Parameters`を使用します。

- 例：

```swift
/// - parameter llamaCount: The number of llamas in the managed herd.
```

<img width="355" alt="MFR_symbol_section_parameter_2x.png" src="https://qiita-image-store.s3.amazonaws.com/0/11914/19e34015-88d6-f4b9-b5a7-430aa77dc1ba.png">


- リファレンス：https://developer.apple.com/library/mac/documentation/Xcode/Reference/xcode_markup_formatting_ref/Parameter.html#//apple_ref/doc/uid/TP40016497-CH28-SW1


### Parameters

- 種類：**section**
- 説明：複数のパラメータの説明を書きます。

- 例：

```swift
/**
  - parameters:
    - cubes: The cubes available for allocation
    - people: The people that require cubes
 */
```

<img width="341" alt="MFR_symbol_section_parameters_2x.png" src="https://qiita-image-store.s3.amazonaws.com/0/11914/e1063a60-eaaa-9085-526b-01c4822ec284.png">


- リファレンス：https://developer.apple.com/library/mac/documentation/Xcode/Reference/xcode_markup_formatting_ref/Parameters.html#//apple_ref/doc/uid/TP40016497-CH24-SW1


### Returns

- 種類：**section**
- 説明：Symbolの返り値を書きます。一つのSymbolに複数の`Returns`キーワードは書けません。（複数書いた時の挙動は決められていない）

- 例：

```swift
/// - returns: A random number between `min` and `max`
```

<img width="362" alt="MFR_symbol_section_returns_2x.png" src="https://qiita-image-store.s3.amazonaws.com/0/11914/2e0a975f-961b-1b9c-9dd2-35711c1ff3ac.png">

- リファレンス：https://developer.apple.com/library/mac/documentation/Xcode/Reference/xcode_markup_formatting_ref/Returns.html#//apple_ref/doc/uid/TP40016497-CH25-SW1


### Throws

- 種類：**section**
- 説明：エラーを返すメソッドや関数の場合に投げるエラーを書きます。一つのSymbolに複数の`Throws`キーワードは書けません。（複数書いた時の挙動は決められていない）

- 例：

```swift
/// - throws: An error of type `FakeArrayError`
```

<img width="370" alt="MFR_symbol_section_throws_2x.png" src="https://qiita-image-store.s3.amazonaws.com/0/11914/7fa98dcb-233d-65d7-0601-38cb6da28260.png">


- リファレンス：https://developer.apple.com/library/mac/documentation/Xcode/Reference/xcode_markup_formatting_ref/Throws.html#//apple_ref/doc/uid/TP40016497-CH26-SW1



# Callout

Calloutは、`Author`や`Version`など、`Description`の項目の中の項目として表示されるものがあたります。


<img width="326" alt="MFR_symbol_description_field_2x.png" src="https://qiita-image-store.s3.amazonaws.com/0/11914/619fec66-fe08-de47-eec6-02f26a3494a3.png">


## Callout一覧

それでは、Calloutも一気に紹介します。

### Attention

- 種類：**callout**
- 説明：使用者への注意喚起を書きます。

- 例：

```swift
/**
  An example of using the attention field
 
  - attention: What I if told you
  you read this line wrong?
 */
```

<img width="261" alt="MFR_symbol_field_attention_2x.png" src="https://qiita-image-store.s3.amazonaws.com/0/11914/bfc35754-d5f2-a6fb-6606-48c724ca982b.png">

- リファレンス：https://developer.apple.com/library/mac/documentation/Xcode/Reference/xcode_markup_formatting_ref/Attention.html



### Author

- 種類：**callout**
- 説明：宣言の作成者を書きます。複数人いる場合は後述の`Authors`を使います。

- 例：

```swift
/**
  An example of using the author field
 
  - author: William Shakespeare
 */
```

<img width="277" alt="MFR_symbol_field_author_2x.png" src="https://qiita-image-store.s3.amazonaws.com/0/11914/ea4c4a13-2056-7575-2dae-f2fbf292fee5.png">


- リファレンス：https://developer.apple.com/library/mac/documentation/Xcode/Reference/xcode_markup_formatting_ref/Author.html


### Authors

- 種類：**callout**
- 説明：宣言の作成者（複数人）を書きます。一人の場合は前述の`Author`を使います。

- 例：

```swift
/**
  An example of using the authors callout
 
  - authors:
   Plato
 
   Aristotle
 
   Other amazing
   classical folk
 */
```

<img width="277" alt="MFR_symbol_field_authors_2x.png" src="https://qiita-image-store.s3.amazonaws.com/0/11914/0342ed27-dd78-f9cd-3495-a2936b1f8f7e.png">


- リファレンス：https://developer.apple.com/library/mac/documentation/Xcode/Reference/xcode_markup_formatting_ref/Authors.html


### Bug

- 種類：**callout**
- 説明：バグについて書きます。一つのSymbolに対して複数設置できるので、複数バグがある場合は一つずつ書くこともできます。

- 例：

```swift
/**
  An example of using the bug field
 
  - bug:
  [*bugExample* contains a memory leak](BugDB://problem/1367823)
 
  - bug:
  [Passing a `UIViewController` crashes *bugExample*](BugDB://problem/2274610)
 */
```

<img width="310" alt="MFR_symbol_field_bug_2x.png" src="https://qiita-image-store.s3.amazonaws.com/0/11914/d3967481-62e5-b941-8ae8-2227d8653211.png">


- リファレンス：https://developer.apple.com/library/mac/documentation/Xcode/Reference/xcode_markup_formatting_ref/Bug.html


### Complexity

- 種類：**callout**
- 説明：計算量について書きます。computed propertyでオーダーがO(1)でないものには、このcalloutを記入して利用者に分かるようにします。(プロパティアクセスは一般的にそれほどの計算量を要さないと思われているため)

- 例：

```swift
/**
  An example of using the complexity field
 
  - complexity:
  The method demonstrates an inefficient way to sort
  using an O(N\*N\*N) (order N-cubed) algorithm
 */
```

<img width="261" alt="MFR_symbol_field_complexity_2x.png" src="https://qiita-image-store.s3.amazonaws.com/0/11914/dfbfc4de-8ace-be99-ed57-d64ab290b2c3.png">


- リファレンス：https://developer.apple.com/library/mac/documentation/Xcode/Reference/xcode_markup_formatting_ref/Complexity.html


### Copyright

- 種類：**callout**
- 説明：コピーライトを書きます。

- 例：

```swift
/**
  An example of using the copyright field
 
  - copyright: Copyright © 1215
  by The Group of Barrons
 */
```

<img width="261" alt="MFR_symbol_field_copyright_2x.png" src="https://qiita-image-store.s3.amazonaws.com/0/11914/67b83873-cf52-a108-72b3-a987cdeced25.png">


- リファレンス：https://developer.apple.com/library/mac/documentation/Xcode/Reference/xcode_markup_formatting_ref/Copyright.html


### Date

- 種類：**callout**
- 説明：日付を書きます。一つのSymbolに対して複数書くことができます。

- 例：

```swift
/**
  An example of using the date field
 
  Last date this example was changed
  - date: August 19, 2015
 
  Days the method produces special results
  - date: 12/31
  - date: 03/17
 */
```

<img width="290" alt="MFR_symbol_field_date_2x.png" src="https://qiita-image-store.s3.amazonaws.com/0/11914/11965e8a-acfc-2fb1-dc63-153e809a106f.png">



- リファレンス：https://developer.apple.com/library/mac/documentation/Xcode/Reference/xcode_markup_formatting_ref/Date.html


### Experiment

- 種類：**callout**
- 説明：実験内容を書きます。一つのSymbolに対して複数書くことができます。

- 例：

```swift
/**
  An example of using the experiment field
 
  - experiment: Pass in a string in the present tense
  - experiment: Pass in a string with no vowels
  - experiment:
  Change the third case statement to work only with consonants
 */
```


<img width="278" alt="MFR_symbol_field_experiment_2x.png" src="https://qiita-image-store.s3.amazonaws.com/0/11914/8bd066d5-8cb5-955a-1719-80fb52e8e52a.png">


- リファレンス：https://developer.apple.com/library/mac/documentation/Xcode/Reference/xcode_markup_formatting_ref/Experiment.html#//apple_ref/doc/uid/TP40016497-CH36-SW1


### Important

- 種類：**callout**
- 説明：重要事項を書きます。一つのSymbolに対して複数書くことができます。

- 例：

```swift
/**
  An example of using the important field
 
  - important:
  "The beginning is the most important part of the work."
  \
  –Plato
 */
```

<img width="312" alt="MFR_symbol_field_important_2x.png" src="https://qiita-image-store.s3.amazonaws.com/0/11914/2c4df7f3-595a-52d0-4e73-1d81a3522ca1.png">


- リファレンス：https://developer.apple.com/library/mac/documentation/Xcode/Reference/xcode_markup_formatting_ref/Important.html#//apple_ref/doc/uid/TP40016497-CH37-SW1


### Invariant

- 種類：**callout**
- 説明：不変な内容（実行中にtrueが保証される条件）を書きます。一つのSymbolに対して複数書くことができます。

- 例：

```swift
/**
  An example of using the invariant field
 
  - invariant:
  The person reference will not change during the execution of this method
 */
```

<img width="315" alt="MFR_symbol_field_invariant_2x.png" src="https://qiita-image-store.s3.amazonaws.com/0/11914/18db2eb2-484e-a65c-261f-313bfb9643cb.png">


- リファレンス：https://developer.apple.com/library/mac/documentation/Xcode/Reference/xcode_markup_formatting_ref/Invariant.html#//apple_ref/doc/uid/TP40016497-CH38-SW1


### Note

- 種類：**callout**
- 説明：注意事項を書きます。一つのSymbolに対して複数書くことができます。

- 例：

```swift
/**
  An example of using the note field
 
  - note:
  This method returns an estimate.
  Use `reallyAccurateReading` to get the best results.
  */
```

<img width="285" alt="MFR_symbol_field_note_2x.png" src="https://qiita-image-store.s3.amazonaws.com/0/11914/b1b03332-a2f8-be05-1cc0-f2260648c2dd.png">


- リファレンス：https://developer.apple.com/library/mac/documentation/Xcode/Reference/xcode_markup_formatting_ref/Note.html#//apple_ref/doc/uid/TP40016497-CH39-SW1


### Precondition

- 種類：**callout**
- 説明：前提条件を書きます。

- 例：

```swift
/**
  An example of using the precondition field
 
  - precondition: The `person` property must be non-nil.
  - precondition: `updatedAddress` must be a valid address.
 */
```

<img width="330" alt="MFR_symbol_field_precondition_2x.png" src="https://qiita-image-store.s3.amazonaws.com/0/11914/ba14623a-51f7-a874-81d4-cc005c1cdea7.png">



- リファレンス：https://developer.apple.com/library/mac/documentation/Xcode/Reference/xcode_markup_formatting_ref/Precondition.html#//apple_ref/doc/uid/TP40016497-CH41-SW1


### Postcondition

- 種類：**callout**
- 説明：完了時に保証される状態を書きます。

- 例：

```swift
/**
  An example of using the postcondition field
 
  - postcondition:
  After completing this method the billing address for
  the person will be set to `updatedAddress` if it is valid.
  Otherwise the billing address will not be changed.
 */
```

<img width="330" alt="MFR_symbol_field_postcondition_2x.png" src="https://qiita-image-store.s3.amazonaws.com/0/11914/e0621630-ad9a-c1b2-7157-fe77a6c2fd15.png">


- リファレンス：https://developer.apple.com/library/mac/documentation/Xcode/Reference/xcode_markup_formatting_ref/Postcondition.html#//apple_ref/doc/uid/TP40016497-CH40-SW1


### Remark

- 種類：**callout**
- 説明：備考等を書きます。

- 例：

```swift
/**
  An example of using the remark field
 
  - remark:
  The performance could be reduced from N-squared to
  N-log-N by switching patterns.
 */
```

<img width="311" alt="MFR_symbol_field_remark_2x.png" src="https://qiita-image-store.s3.amazonaws.com/0/11914/899d2d69-02c8-493b-b327-b708a6004233.png">


- リファレンス：https://developer.apple.com/library/mac/documentation/Xcode/Reference/xcode_markup_formatting_ref/Remark.html#//apple_ref/doc/uid/TP40016497-CH42-SW1


### Requires

- 種類：**callout**
- 説明：必要事項を書きます。

- 例：

```swift
/**
  An example of using the requires field
 
  - requires: `start <= end`.
  - requires: `count > 0`.
 */
```

<img width="322" alt="MFR_symbol_field_requires_2x.png" src="https://qiita-image-store.s3.amazonaws.com/0/11914/5d036681-596e-9545-db83-bf32f9be684b.png">


- リファレンス：https://developer.apple.com/library/mac/documentation/Xcode/Reference/xcode_markup_formatting_ref/Requires.html


### SeeAlso

- 種類：**callout**
- 説明：関連情報や参照を書きます。一つのSymbolに対して複数書くことができます。

- 例：

```swift
/**
  An example of using the seealso field
 
  - seealso:
  [The Swift Standard Library Reference](https://developer.apple.com/library/prerelease/ios//documentation/General/Reference/SwiftStandardLibraryReference/index.html)
 */
```

<img width="330" alt="MFR_symbol_field_seealso_2x.png" src="https://qiita-image-store.s3.amazonaws.com/0/11914/d724fbcf-fc76-014f-3bc2-3de556942d6f.png">


- リファレンス：https://developer.apple.com/library/mac/documentation/Xcode/Reference/xcode_markup_formatting_ref/SeeAlso.html#//apple_ref/doc/uid/TP40016497-CH45-SW1


### Since

- 種類：**callout**
- 説明：Symbolが利用可能になった時の情報（OS情報やフレームワークのバージョン、日付など）を書きます。一つのSymbolに対して複数書くことができます。

- 例：

```swift
/**
  An example of using the since field
 
  - since: First available in Mac OS 7
 */
```

<img width="293" alt="MFR_symbol_field_since_2x.png" src="https://qiita-image-store.s3.amazonaws.com/0/11914/e393e6d4-1f02-40dd-91b9-a84b9c8ed91f.png">


- リファレンス：https://developer.apple.com/library/mac/documentation/Xcode/Reference/xcode_markup_formatting_ref/Since.html#//apple_ref/doc/uid/TP40016497-CH46-SW1


### Todo

- 種類：**callout**
- 説明：Symbolを完成させるためや更新するためにやるべきことを書きます。一つのSymbolに対して複数書くことができます。

- 例：

```swift
/**
  An example of using the todo field
 
  - todo: Run code coverage and add tests
 */
```

<img width="282" alt="MFR_symbol_field_todo_2x.png" src="https://qiita-image-store.s3.amazonaws.com/0/11914/4ddf4cb6-791b-2b3b-7bfd-18bc52bfebcd.png">

- リファレンス：https://developer.apple.com/library/mac/documentation/Xcode/Reference/xcode_markup_formatting_ref/Todo.html#//apple_ref/doc/uid/TP40016497-CH47-SW1


### Version

- 種類：**callout**
- 説明：バージョン情報を書きます。一つのSymbolに対して複数書くことができます。

- 例：

```swift
/**
  An example of using the version field
 
  - version: 0.1 (61A329)
 */
```

<img width="261" alt="MFR_symbol_field_version_2x.png" src="https://qiita-image-store.s3.amazonaws.com/0/11914/4cd19acf-ce2d-9c35-f540-42a00b29e4e0.png">


- リファレンス：https://developer.apple.com/library/mac/documentation/Xcode/Reference/xcode_markup_formatting_ref/Version.html#//apple_ref/doc/uid/TP40016497-CH48-SW1



### Warning

- 種類：**callout**
- 説明：警告事項を書きます。一つのSymbolに対して複数書くことができます。

- 例：

```swift
/**
  An example of using the warning field
 
  - warning:
  Not all code paths for this method have been tested
 */
```

<img width="380" alt="MFR_symbol_field_warning_2x.png" src="https://qiita-image-store.s3.amazonaws.com/0/11914/836db2c7-7455-f694-a83d-4e491201e273.png">


- リファレンス：https://developer.apple.com/library/mac/documentation/Xcode/Reference/xcode_markup_formatting_ref/Warning.html#//apple_ref/doc/uid/TP40016497-CH49-SW1


# 終わりに

ドキュメンテーションコメントも適切に書いて、誰にでもわかりやすいコードを書きたいですね。

また、書き終えてから見つけたのですが、[こちらのスライド](http://www.slideshare.net/tomohirokumagai54/swift-54759764)にて今回の内容にあたることも含めて、ドキュメンテーションコメントについて丁寧に解説されているので、とても勉強になります。

# 参考

- [Swift.org - API Design Guidelines](https://swift.org/documentation/api-design-guidelines/)
- [Swift 2 で強化されたコメント表記をまとめた #2 - Qiita](http://qiita.com/roworks/items/cd5cb05bd83585325db7)