Xcode8でのドキュメントコーディング

スマートテック・ベンチャーズの@Nick_paperです。

今回はSwiftのDocumentコーディングについて紹介します。


# Abstract

Xcodeもバージョン8.0にアップデートされましたね。
ドキュメントコードが拡張されたことはご存知でしょうか？

私は今回ここに再フォーカスしてみたいと思います。

Check it out!


# First

まずはXcodeのドキュメント骨格を自動で生成させる方法です。
プラグインすることなく標準できるようになりました。

> **Editor > Structure > Add Documentation**

![スクリーンショット 2016-12-24 0.26.42.png](https://qiita-image-store.s3.amazonaws.com/0/133774/e1839b06-2bdf-50b3-f305-039d59d151fc.png)

ショートカットキーならば「**Command + Option + /**」を使って生成することも有効です。

```
/// <#Description#>
///
/// - parameter bar: <#bar description#>
///
/// - returns: <#return value description#>
```

と表示されるはず.....。

## Something is wrong...

うまく機能しないこともあるようですね、

![スクリーンショット 2016-12-24 0.09.59.png](https://qiita-image-store.s3.amazonaws.com/0/133774/75dd8424-4fb4-eda2-b1e6-36f817a9bbef.png)



もしもうまくいかない場合は[こちら](https://twitter.com/kolpanic/status/763323546814844928
)を試してみて下さい。
> sudo /usr/libexec/xpccachectl
> Reboot your system.

![スクリーンショット 2016-12-24 0.14.50.png](https://qiita-image-store.s3.amazonaws.com/0/133774/e2621be4-8b26-57e9-56e0-55a3474de85f.png)
この後に再起動すればOKです。



# Second
Xcodeは、あなたが選択したシンボルを読み取って、doc-commentのアウトラインを追加してくれます。
もちろん、名前を付けたパラメーターと返り値の型（存在する場合のみ）も含まれます。

## 追加機能
次のようなコメントも追加することができます。
- notes
- warnings
- authorship
- date
- complexity details


## Closure
クロージャーパラメーターにも対応するようになりました。

既存のドキュメントでは、以下のようにクロージャーパラメーターを含みませんが、

![Screen-Shot-2016-09-16-at-11.06.41-AM.png](https://qiita-image-store.s3.amazonaws.com/0/133774/ff46590e-1ec4-5d16-0c3f-4f3b1856190e.png)

**(_ line: String)**のような内部引数を追加することで、コードドキュメントを拡張することもできます。
Xcodeは情報を拾い上げ、特別なクロージャーパラメーターの欄を生成します。

こちらがコードドキュメントを拡張している例です。

![Screen-Shot-2016-09-16-at-11.09.13-AM.png](https://qiita-image-store.s3.amazonaws.com/0/133774/85dc66d0-95c8-806b-7793-69c402be7709.png)

本来のswiftの枠組みのように、処理が入れ子になったパラメーターや返り値, そしてthrowも同様に生成できます。

ちなみに現在、名前が付いたクロージャーパラメーターをサポートするのはXcodeだけのようです。


# Give it a go

例えば、次のようなメソッドに対するドキュメントを記入します。

![スクリーンショット 2016-12-24 6.14.15.png](https://qiita-image-store.s3.amazonaws.com/0/133774/26c03f47-b6fe-e456-8c0d-88cba0585337.png)

それから、**sayMerryChristmas**が呼び出されるところで「**option + クリック**」を行います。
以下のようにドキュメントコーディングした内容が説明としても反映されます。

![スクリーンショット 2016-12-24 6.28.03.png](https://qiita-image-store.s3.amazonaws.com/0/133774/e9930beb-8ce6-5589-79a4-0c6519197435.png)

次のように追記することもできます。

![スクリーンショット 2016-12-24 7.12.46.png](https://qiita-image-store.s3.amazonaws.com/0/133774/ed0e6d31-cc6e-5ff4-f609-07880a1fa0be.png)

再度、確認してみると...

![スクリーンショット 2016-12-24 7.12.34.png](https://qiita-image-store.s3.amazonaws.com/0/133774/85ff403f-1434-8ffd-5084-d15e42ba85e6.png)

内容が反映されているのが確認できます。


# Reference

- [swift/bindings/xml/comment-xml-schema.rng](https://github.com/apple/swift/blob/c20f3db09e41ca0dcaae885a6c10164a8074612e/bindings/xml/comment-xml-schema.rng)
- [Swiftでドキュメントコメントを正しく書こう！](http://grandbig.github.io/blog/2016/01/24/swift-document-comment/)
- [Xcode 8 Document Coding Enhancements](http://ericasadun.com/2016/09/16/xcode-8-document-coding-enhancements/)


# Finally

[スマートテック・ベンチャーズ](https://www.wantedly.com/projects/72590?ql=gaJpZM4AKYPb)は未経験者や、経験者だけどもSwift&iOSやってみたいという人を募集しています。
どんな小さな一歩も、続けていけば大きな飛躍に！　

最後のバッターは @ktaguchi  さんです。
乞うご期待を！

Merry Christmas!!