swift ドキュメントコメント

EZ-NET 熊⾕友宏 http://ez-net.jp/

2015.11.02

ドキュメントコメントXcode 7 & Swift 2

熊谷友宏EZ-NET http://ez-net.jp/ @es_kumagai

CodePiece

iOS, OS X, Apple Watch アプリ

ソースコードを Twitter と Gist に同時投稿できる。

いつもの電卓計算式も見える電卓アプリ。 watchOS 1 対応

音で再配達ゴッド簡単操作で再配達の申し込み。

EZ-NET IP PhoneiPhone でひかり電話を使う。自宅 LAN からの利用専用


横浜 iPhone 開発者勉強会#yidev

勉強会

わいわい・ゆるく、iPhone 開発者のみんなで楽しく過ごすのが目的の会

【横浜・馬車道】カジュアル Swift 勉強会#cswift

ゆるくみんなで Swift を語らえる場を作りたくて始めた会

【横浜・青葉台】

第21回を 2015-12-12 に開催第3回を 2015-11-14 に開催


Xcode 5 徹底解説 MOSA

書籍 / 登壇

Xcode 5 の全機能を徹底的に解説した本

OSX/iOS 系の歴史深い有料会員制の勉強会

紙版は絶版、電子書籍は販売中秀和システム 10x-Eng.com で取扱予定

2015-11-07 の MSM2015 で Swift 2 を始めたい人向けの話で登壇

Xcode 7 でも役立つはず法人会員も多数

http://10x-eng.com

Xcode 5 徹底解説著書

> 全機能を徹底解説 ✔ 各画面の使い方 ✔ プロジェクトやコードの編集 ✔ インターフェイスビルダー ✔ ビルドとデバッグ ✔ ユニットテストと Bot

> 紙版は絶版 (2015/08/21) > 電子書籍版は販売中

✔ 10x-Eng.com でも取扱予定2014/04/28 - 2015/08/21

750 ページ

Swift 2 の話をする予定MSM 2015

> MSM 2015 ✔ NPO 法人 MOSA 主催 ✔ 有料イベント（会員制） ✔ 年に一度の２日間に渡るお祭り的なイベント

✔ Apple 最新技術の話題満載

> NPO 法人 MOSA ✔ 10 年以上の活動実績 ✔ 法人会員での参加も多い印象

2015/11/06 - 2015/11/07http://www.mosa.gr.jp/

Xcode 7̶ 2015.09.16 ̶

▶ Swift 2 ▶ 新 OS サポート ▶ UI テスト ▶ コードカバレッジ ▶ ドキュメントコメント ▶ 呼出階層検索ナビゲーター ▶ インターフェイス定義の確認 ▶ 無料のオンデバイス開発

新機能Xcode 7

▶ コンテナービュー ▶ スタックビュー ▶ ストーリーボード参照 ▶ オンデマンドリソース

ドキュメントコメント

▶ 型や機能に説明を記載できる ▶ コード補完時に概要を見られる ▶ クイックヘルプで詳細を見られる

機能ドキュメントコメント

▶ Markdown のような書式 • テキストの装飾 • 画像の挿入 • リンクの挿入

▶ プレイグラウンド専用機能 • ページナビゲーション • リッチコメント描画

▶ Swift 専用

機能強化されたドキュメントコメント

1. シンボルの文書化 ▶ 型や機能にドキュメントを添える ▶ クイックヘルプやコード補完で見れる ▶ ソースコードとプレイグラウンドで使える

2. リッチコメント ▶ 見栄えの良いコメントが書ける ▶ プレイグラウンドをドキュメントとして見せる ▶ プレイグラウンド専用

利用できる場面強化されたドキュメントコメント

1. シンボルの文書化

▶ 型や機能にドキュメントを添える ▶ 専用の書式で意味付けできる ▶ ソースコードとプレイグラウンドの両方で使用できる

▶ クイックヘルプやコード補完で見れる

特徴シンボルの文書化

▶ コメント行内でマークアップする ▶ コメント行は次の２通りで書く (a) /// でコメント行を書く（複数行可） (b) /** ～ */ でコメントブロックを書く

書き方シンボルの文書化

記載シンボルの文書化

/// 指定したターゲットをビルドします。 /// 設定を追加することで異なるオプションでビルドできます。 /// /// - precondition: /// ビルド対象のプロジェクトが開かれている必要があります。 /// /// - parameters: /// - target: ビルドするターゲットです。 /// - configuration: ビルドで使う設定です。 /// /// - returns: ビルドの実行結果を返します。 /// - throws: エラー時は BuildError が投げられます。

func build(target:Target, config:Config) throws -> Report {

▶ コード補完

表示シンボルの文書化

▶ クイックヘルプ

2. リッチコメント

▶ プレイグラウンドだけで使える ▶ 見栄えの良いコメントが書ける ▶ プレイグラウンドファイルをまるごとドキュメントとして見せる

特徴リッチコメント

▶ コメント行内でマークアップする ▶ コメント行は次の２通りで書く (A) //: でコメント行を書く（複数行可） (B) /*: ～ */ でコメントブロックを書く

書き方リッチコメント

記載リッチコメント

//: ## `reduce` メソッド //: 配列の **総和** を簡単に計算できます。

//: ### 準備

let values = [1, 3, 8, 20] //: ### 実行

let sum = values.reduce(0, combine: +)

表示リッチコメント

▶ ファイルインスペクターで切り替える

表示の切り替えリッチコメント

オン・オフで切り替わる

▶ リッチコメント表示中でも

• 実行コードを編集できる

▶ リッチコメント表示中は

• リッチコメントを編集できない • 通常のコメントは編集できる

留意点リッチコメント

マークアップ

▶ シンボルの文書化やリッチコメントの内容に付加情報を添える

▶ コマンドを使ってマークアップする ▶ コマンドはインデントレベルが大事

• インデントによって解釈が変わる • コメントブロックの最初が第一レベル

▶ Markdown みたいな書式

基本マークアップ

1. 行書式コマンド 2. テキスト書式コマンド 3. シンボル文書化コマンド 4. ページナビゲーションコマンド

コマンドの種類マークアップ

リッチコメント専用

シンボル文書化専用

1. 行書式コマンド

シンボル文書化リッチコメント

▶ 行単位で書式を指定する特徴

行書式コマンド

基本書式

行書式コマンド行テキスト


空白必須

▶ 見出し ▶ ブロック引用 ▶ 箇条書き ▶ 番号付き箇条書き ▶ コードブロック ▶ 水平線 ▶ リンク参照

種類行書式コマンド


見出し


▶ 行を見出しとして扱う ▶ 先頭の # の数でレベルを指定（３レベルまで）

見出し行書式コマンド

記載方法

最初の見出しです。


次の見出しです。

#

##

記号の数でレベル指定

空白必須


//: 見出しを表示します。 //: # 最初の見出しです。 //: ## 次の見出しです。 //: 以上

表示例（リッチコメント）

リッチコメント

記載例

シンボル文書化

▶ 見出しを次行の下線で表現する • レベル１は === で表現する • レベル２は --- で表現する

見出し（別の書き方）行書式コマンド

記載方法


見出しです。

＝＝＝＝＝＝

↩最初は空行

２行目で下線を表現



//: 見出しを表示します。 //: //: 見出しです。 //: =========== //: 以上



記載例



ブロック引用


▶ 内容を引用として扱う ▶ 連続で書くと１つとして扱われる

ブロック引用行書式コマンド

記載方法

> 引用してきたテキストを記載します。


> 複数行に分けて続きを記載できます。

空白必須↩

最後は空行

ブロック引用行書式コマンド

//: 次のような説明が記載されています。 //: //: > 引用してきたテキストを記載します。 //: > 複数行に分けて続きを記載できます。 //: //: 以上



記載例



箇条書き


▶ 先頭は *, +, - のどれかで揃える ▶ 同レベルの項目は同じインデントで書く

箇条書き行書式コマンド

記載方法

* 最初の項目


* ふたつ目の項目

↩最後は空行

空白必須

インデントを揃える

ふたつ目にぶら下げた項目*

レベルを変えられる

箇条書き行書式コマンド

//: 項目を箇条書きします。 //: * 最初の項目 //: * ふたつ目の項目 //: * ふたつ目にぶら下げた項目 //: //: 以上



記載例



番号付き箇条書き


▶ 先頭を番号と .で始める ▶ どんな番号でも連番に振り直される

番号付き箇条書き行書式コマンド

記載方法

. 最初の項目


. ふたつ目の項目

↩最後は空行

インデントを揃える

ぶら下げた項目.

レベルを変えられる

1

1

1


//: 項目を箇条書きします。 //: 1. 最初の項目 //: 1. ふたつ目の項目 //: 1. ふたつ目にぶら下げた項目 //: //: 以上



記載例



//: 3. 最初の項目 //: 3. ふたつ目の項目

シンボル文書化は１番から


採番のされ方が異なる


リッチコメントは指定番号から表示例


コードブロック


▶ 内容をプログラムコードとして扱う ▶ インデントして内容を記載する

コードブロック行書式コマンド

記載方法

let 数値列 = [1, 3, 5, 7]


let 総和 = 数値列.reduce(0, combine: +)

↩

最後は空行

↩ 最初は空行

インデント必須

```

▶ 上下を ``` で括って書ける ▶ シンボル文書化だけで使える

コードブロック（別の書き方）行書式コマンド

記載方法


空行不要

let 数値列 = [1, 3, 5, 7]

let 総和 = 数値列.reduce(0, combine: +)

```

インデント不要

コードブロック行書式コマンド

//: サンプルコードです。 //: //: let 数値列 = [1, 3, 5, 7] //: let 総和 = 数値列.reduce(0, combine: +) //: //: 以上



記載例



水平線


▶ 行を水平線にする ▶ ３文字以上のハイフンで表現する

水平線行書式コマンド

記載方法


↩

最後は空行

↩ 最初は空行

−−−

３文字以上

水平線行書式コマンド

//: 水平線で分断します。 //: //: - - - //: //: 以上



記載例



リンク参照


▶ リンク付きテキストを定義する ▶ 定義後に本文内でテキストを使う

リンク参照行書式コマンド

記載方法

[ テキスト


定義したテキスト

↩

必要に応じて最初は改行

] URL " "ホバーテキスト

[ テキスト ] を使う

リンク参照行書式コマンド

//: テキストにリンクを定義して使います。 //: //: [EZ-NET]: http://ez-net.jp "EZ-NET" //: 定義したテキスト [EZ-NET] を使います。 //: 以上



記載例


http://ez-net.jp

2. テキスト書式コマンド


▶ 文字列単位で書式を指定する特徴

テキスト書式コマンド

基本書式

コマンドテキスト


コマンドテキストテキスト

▶ 強調表記 ▶ コード表記 ▶ 画像表記 ▶ リンク参照 ▶ 記号のエスケープ

種類テキスト書式コマンド


強調表記


▶ テキストを強調して表示する ▶ 両側を * または _ で括る

強調表記 : 斜体テキスト書式コマンド

記載方法

* 二種類の変数


*Swift にはがあります。

目的の語句を囲う

強調表記 : 斜体テキスト書式コマンド

//: テキストの一部を強調して表現します。 //: //: Swift には *二種類の変数* があります。



記載例


▶ テキストを強調して表示する ▶ 両側を ** または __ で括る

強調表記 : 太字テキスト書式コマンド

記載方法

** 構造体


**Swift はデータをで表現します。

強調表記 : 太字テキスト書式コマンド

//: テキストの一部を強調して表現します。 //: //: Swift ではデータを **構造体** で表現します。



記載例


▶ テキストを強調して表示する ▶ 両側を *** または ___ で括る

強調表記 : 太字と斜体テキスト書式コマンド

記載方法

*** 変数で振る舞いが変化


***構造体はします。

強調表記 : 太字と斜体テキスト書式コマンド

//: テキストの一部を強調して表現します。 //: //: 構造体は ***変数で振る舞いが変化*** します。



記載例



コード表記


▶ テキストがコードであることを表現する ▶ 両側を ` で括る

コード表記テキスト書式コマンド

記載方法

` let


`Swift では原則で変数を扱います。

コード表記テキスト書式コマンド

//: テキストの一部をコードとして表現します。 //: //: Swift では原則 `let` で変数を扱います。



記載例



画像表記


▶ テキストに画像を挿入する ▶ 場面によって表現が変わる様子 • リッチコメントではブロック要素 • シンボル文書化ではインライン要素

画像表記テキスト書式コマンド

構文

[ ポップアップ


]! 交代テキスト ( 画像パス " "

必要に応じて

)

画像表記テキスト書式コマンド

//: コメント内に画像を挿入します。 //: //: ![Note](https://ez-net.jp/note.png) Swift は //: 目まぐるしく進化します。

表示例


記載例


シンボル文書化はインラインリッチコメントはブロック扱い

▶ HTML タグで画像を挿入する ▶ シンボルの文書化だけで使える様子 ▶ 正式な方法かは不明

画像サイズを変えたい時テキスト書式コマンド



/// コメント内に画像を挿入します。 /// /// <img src="https://ez-net.jp/note.png" style="width: 14px”/> Swift は /// 目まぐるしく進化します。

記載例


画像サイズを変えたい時

表示例（シンボル文書化）


画像のカレントパステキスト書式コマンド


シンボルの文書化




リンク参照


テキスト

▶ URL リンク付きのテキストを表現する ▶ テキスト内で自由に使える

リンク参照テキスト書式コマンド

記載方法

[ テキスト


] URL( ) テキスト

リンク参照テキスト書式コマンド

//: テキスト書式コマンドなら //: 事前定義なく [リンク](http://ez-net.jp) を使えます。



記載例


http://ez-net.jp


記号のエスケープ


テキスト

▶ 特別な記号をそのまま表示できる

記号のエスケープテキスト書式コマンド

記載方法

\ 記号


テキスト

記号のエスケープテキスト書式コマンド

//: 次のように書くとリンクを挿入できます。 //: //: \[タイトル](https://ez-net.jp)



記載例


3. シンボル文書化コマンド


▶ シンボルの説明に意味を添える ▶ ４つのセクションで構成される ▶ ハイフン記号で書き始める

特徴シンボル文書化コマンド

書式

- コマンド


: コンテンツ

コンテンツの続きを次行に記載できる

↩最後は改行か別のコマンド

必要に応じて

1. Description セクション 2. Parameters セクション 3. Returns セクション 4. Throws セクション

４つのセクションシンボル文書化コマンド


セクション

Description


コンテンツ

▶ シンボルの説明を扱う ▶ コマンドを明記しないテキストが所属する ▶ 複数の Description フィールドを持てる

Description セクションシンボル文書化コマンド

基本書式


コマンドを含めずテキストを記載

Description セクションシンボル文書化コマンド

/// 現在のターゲットを取得します。 var currentTarget:Target

表示例

記載例


▶ Description セクションに情報を添える ▶ いくつでも追加できる

Description フィールドシンボル文書化コマンド

基本書式


- フィールド名 : 説明文

説明文の続きを次行に記載できる

↩最後は改行か次のコマンド

必要に応じて

Description フィールドシンボル文書化コマンド

/// ストリームの末端まで読み進められているか調べます。 /// - precondition: ストリームが開かれている必要があります。 /// - note: 文字列ストリームでは NUL を末端とみなします。

func isEOF(stream:Stream) -> String {

表示例

記載例


Description で使えるフィールド名 (1/4)シンボル文書化コマンド


- : 注目して欲しい情報を記載attention

- : 著作者名author

- : バグに関する情報を記載bug

- : アルゴリズム的な複雑さを記載Complexity

- : 著作権に関する情報を記載copyright

- : 何らかの日付情報を記載date

- : 試験的な機能であることを記載experiment



- : 使用上の重要情報を記載important

- : 実行中に変化しないものを明記invariant

- : 補足情報を記載note

- : 実行に必要な値の前提条件を記載precondition

- : 実行直後の値の変化を記載postcondition

- : シンボルの解説を記載remark

- : 実行に必要な環境情報を記載requires



- : 別の参考資料を記載seealso

- : いつから使えるようになったかを記載since

- : 実行完了に必要な追加タスクを記載todo

- : シンボルのバージョン情報を記載version

- : 使用上の注意事項を記載warning

- :authors



基本書式

↩

▶ 複数人数の著作者情報を記載

著作者名

著作者名

↩

最後は改行

改行で次の人

セクション

Parameters


▶ シンボルの引数を扱う ▶ 複数のフィールドを持てる

Parameters セクションシンボル文書化コマンド

基本書式


- 引数名 : 説明文



必要に応じて

parameter

Parameters セクションシンボル文書化コマンド

/// ストリームに値を書き込みます。 /// - parameter value: 書き込む値です。 /// - parameter stream: 書き込み先のストリームです。

func write(value:String, stream:Stream) {

表示例

記載例


- :parameters

Parameters の一括定義シンボル文書化コマンド


基本書式

▶ 複数の引数情報を記載

↩

説明文- :引数名

説明文- :引数名

インデント必須

最後は改行か次のコマンド

Parameters の一括定義シンボル文書化コマンド

/// ストリームに値を書き込みます。 /// - parameters: /// - value: 書き込む値です。 /// - stream: 書き込み先のストリームです。 func write(value:String, stream:Stream) {

表示例

記載例


セクション

Returns


▶ シンボルの戻り値を扱う ▶ ひとつだけ指定できる

Returns セクションシンボル文書化コマンド

基本書式


- 説明文



必要に応じて

returns :

Returns セクションシンボル文書化コマンド

/// ストリームから値を読み込みます。 /// - returns: 読み取った文字列を返します。

func read(stream:Stream) -> String {

表示例

記載例


セクション

Throws


▶ エラーに関する情報を扱う ▶ ひとつだけ指定できる

Throws セクションシンボル文書化コマンド

基本書式


- 説明文



必要に応じて

throws :

Throws セクションシンボル文書化コマンド

/// ストリームに値を書き込みます。 /// - throws: ストリームが開かれてないと /// Stream.NotOpenError が発生ます。

func write(value:String, stream:Stream) throws {

表示例

記載例



4. ページナビゲーションコマンド


▶ ページ移動するための機能

• 指定ページに移動する • 前後のページに移動する

▶ リッチコメントだけで使える

特徴ページナビゲーションコマンド


[ 表題 ] 移動先ページ名( )

▶ 指定したページ名へのリンクを作れる ▶ ページ名の空白文字は %20 に置き換える

指定ページに移動ページナビゲーションコマンド

記載方法


[ 表題 ] @next( )

▶ 次のページへのリンクを作れる ▶ 順番はプロジェクトナビゲーターで指定する

次のページに移動ページナビゲーションコマンド

記載方法


[ 表題 ] @previous( )

▶ 前のページへのリンクを作れる ▶ 順番はプロジェクトナビゲーターで指定する

前のページに移動ページナビゲーションコマンド

記載方法


ページ


▶ プレイグラウンド内に複数のページを追加できる機能

▶ プロジェクトナビゲーターで管理する

Playground ページページナビゲーションコマンド


▶ 各ページがリソースを持てる ▶ Playground ファイル直下のリソースはすべてのページで利用できる様子

Playground ページのリソースページナビゲーションコマンド


このページ専用

全ページで使える

ページ作成


▶ プロジェクトナビゲーターから作成

ページの新規作成Playground ページ


新規作成

⌥ + Click

▶ プロジェクトナビゲーターで登録されている順番で管理される

ページの順番Playground ページ


ページはこの順番

ページ移動


指定ページに移動ページ移動

//: 目次 //: //: [セクション A](Section%20A) //: //: [セクション B](Section%20B)

表示例

記載例


指定ページに移動ページ移動

//: [前のページ](@previous) //: //: [次のページ](@next)

表示例

記載例


まとめ

▶ シンボルに説明を記載できる

• セクションで詳しく意味づけできる • コード補完やクイックヘルプで見れる • テキストを装飾できる

▶ Playground コメントの可能性が広がる

• テキストを装飾できる • ページ移動のリンクが貼れる

まとめドキュメントコメント

▶ コメントの書き方 ▶ 強化されたドキュメントコメント ▶ シンボルの文書化 ▶ リッチコメント

▶ マークアップ ▶ 行書式コマンド ▶ テキスト書式コマンド ▶ シンボル文書化コマンド ▶ ページナビゲーションコマンド

ドキュメントコメントXcode 7 + Swift 2

おまけドキュメントコメント

もしかしてHTML タグが使える？

HTML タグを混ぜられる？ドキュメントコメント

説明の中で HTML を使うと


クイックヘルプに反映される

HTML タグを混ぜられる？

スタイルシートも混ぜられる？ドキュメントコメント

スタイルを説明に添えると


クイックヘルプに反映される

スタイルシートも混ぜられる？

スタイル指定はお勧めできない？ドキュメントコメント

▶ コメント毎にスタイルが必要 ▶ コメントの度に本格的なスタイルを記載するのは非現実的

▶ 見た目の統一性がなくなる ▶ そもそも正式に使える機能か判らない

もしかしてJavaScript が使える？

JavaScript を混ぜられる？ドキュメントコメント

クイックヘルプで実行される

説明の中で script を使うと

JavaScript を混ぜられる？ドキュメントコメント

コード補完だとバレバレ

▶ ただしコード補完ではスクリプトがそのまま表示される

JavaScript 埋め込みはお勧めできない？ドキュメントコメント

▶ 正式に使える機能か判らない ▶ コード補完でコードがそのまま表示される ▶ そもそもそこまで必要なのか？

おすすめドキュメントコメント

絵文字を活用するドキュメントコメント

説明の中で絵文字を使うと


コード補完で表示される


クイックヘルプで表示される

絵文字で検索できる！ドキュメントコメント

検索できる！

絵文字を使って …

おしまい ☺

swift ドキュメントコメント

Software