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

More than 1 year has passed since last update.

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

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


Abstract

Xcodeもバージョン8.0にアップデートされましたね。

ドキュメントコードが拡張されたことはご存知でしょうか?

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

Check it out!


First

まずはXcodeのドキュメント骨格を自動で生成させる方法です。

プラグインすることなく標準できるようになりました。


Editor > Structure > Add Documentation


スクリーンショット 2016-12-24 0.26.42.png

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

/// <#Description#>

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

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


Something is wrong...

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

スクリーンショット 2016-12-24 0.09.59.png

もしもうまくいかない場合はこちらを試してみて下さい。


sudo /usr/libexec/xpccachectl

Reboot your system.


スクリーンショット 2016-12-24 0.14.50.png

この後に再起動すればOKです。


Second

Xcodeは、あなたが選択したシンボルを読み取って、doc-commentのアウトラインを追加してくれます。

もちろん、名前を付けたパラメーターと返り値の型(存在する場合のみ)も含まれます。


追加機能

次のようなコメントも追加することができます。

- notes

- warnings

- authorship

- date

- complexity details


Closure

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

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

Screen-Shot-2016-09-16-at-11.06.41-AM.png

(_ line: String)のような内部引数を追加することで、コードドキュメントを拡張することもできます。

Xcodeは情報を拾い上げ、特別なクロージャーパラメーターの欄を生成します。

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

Screen-Shot-2016-09-16-at-11.09.13-AM.png

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

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


Give it a go

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

スクリーンショット 2016-12-24 6.14.15.png

それから、sayMerryChristmasが呼び出されるところで「option + クリック」を行います。

以下のようにドキュメントコーディングした内容が説明としても反映されます。

スクリーンショット 2016-12-24 6.28.03.png

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

スクリーンショット 2016-12-24 7.12.46.png

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

スクリーンショット 2016-12-24 7.12.34.png

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


Reference


Finally

スマートテック・ベンチャーズは未経験者や、経験者だけどもSwift&iOSやってみたいという人を募集しています。

どんな小さな一歩も、続けていけば大きな飛躍に! 

最後のバッターは @ktaguchi さんです。

乞うご期待を!

Merry Christmas!!