スマートテック・ベンチャーズの@Nick_paperです。
今回はSwiftのDocumentコーディングについて紹介します。
Abstract
Xcodeもバージョン8.0にアップデートされましたね。
ドキュメントコードが拡張されたことはご存知でしょうか？
私は今回ここに再フォーカスしてみたいと思います。
Check it out!
First
まずはXcodeのドキュメント骨格を自動で生成させる方法です。
プラグインすることなく標準できるようになりました。
Editor > Structure > Add Documentation
ショートカットキーならば「Command + Option + /」を使って生成することも有効です。
/// <#Description#>
///
/// - parameter bar: <#bar description#>
///
/// - returns: <#return value description#>
と表示されるはず.....。
Something is wrong...
うまく機能しないこともあるようですね、
もしもうまくいかない場合はこちらを試してみて下さい。
sudo /usr/libexec/xpccachectl
Reboot your system.
この後に再起動すればOKです。
Second
Xcodeは、あなたが選択したシンボルを読み取って、doc-commentのアウトラインを追加してくれます。
もちろん、名前を付けたパラメーターと返り値の型（存在する場合のみ）も含まれます。
追加機能
次のようなコメントも追加することができます。
- notes
- warnings
- authorship
- date
- complexity details
Closure
クロージャーパラメーターにも対応するようになりました。
既存のドキュメントでは、以下のようにクロージャーパラメーターを含みませんが、
**(_ line: String)**のような内部引数を追加することで、コードドキュメントを拡張することもできます。
Xcodeは情報を拾い上げ、特別なクロージャーパラメーターの欄を生成します。
こちらがコードドキュメントを拡張している例です。
本来のswiftの枠組みのように、処理が入れ子になったパラメーターや返り値, そしてthrowも同様に生成できます。
ちなみに現在、名前が付いたクロージャーパラメーターをサポートするのはXcodeだけのようです。
Give it a go
例えば、次のようなメソッドに対するドキュメントを記入します。
それから、sayMerryChristmasが呼び出されるところで「option + クリック」を行います。
以下のようにドキュメントコーディングした内容が説明としても反映されます。
次のように追記することもできます。
再度、確認してみると...
内容が反映されているのが確認できます。
Reference
- swift/bindings/xml/comment-xml-schema.rng
- Swiftでドキュメントコメントを正しく書こう！
- Xcode 8 Document Coding Enhancements
Finally
スマートテック・ベンチャーズは未経験者や、経験者だけどもSwift&iOSやってみたいという人を募集しています。
どんな小さな一歩も、続けていけば大きな飛躍に！
最後のバッターは @ktaguchi さんです。
乞うご期待を！
Merry Christmas!!