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 Phone
iPhone でひかり電話を使う。
自宅 LAN からの利用専用

熊谷友宏
@es_kumagai
横浜 iPhone 開発者勉強会
#yidev
勉強会
わいわい・ゆるく、iPhone 開発者の 
みんなで楽しく過ごすのが目的の会
【横浜・馬車道】
カジュアル Swift 勉強会
#cswift
ゆるくみんなで Swift を語らえる場を 
作りたくて始めた会
【横浜・青葉台】
第21回を 2015-12-12 に開催第3回を 2015-11-14 に開催

熊谷友宏
@es_kumagai
Xcode 5 徹底解説 MOSA
書籍 / 登壇
Xcode 5 の全機能を 
徹底的に解説した本
OSX/iOS 系の歴史深い 
有料会員制の勉強会
紙版は絶版、電子書籍は販売中
秀和システム 10x-Eng.com で取扱予定
2015-11-07 の MSM2015 で
Swift 2 を始めたい人向けの話で登壇
Xcode 7 でも役立つはず法人会員も多数

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/07
http://www.mosa.gr.jp/

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

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

▶ Markdown のような書式
• テキストの装飾
• 画像の挿入
• リンクの挿入
▶ プレイグラウンド専用機能
• ページナビゲーション
• リッチコメント描画
▶ Swift 専用
機能
強化されたドキュメントコメント

1. シンボルの文書化
▶ 型や機能にドキュメントを添える
▶ クイックヘルプやコード補完で見れる
▶ ソースコードとプレイグラウンドで使える
2. リッチコメント
▶ 見栄えの良いコメントが書ける
▶ プレイグラウンドをドキュメントとして見せる
▶ プレイグラウンド専用
利用できる場面
強化されたドキュメントコメント

▶ 型や機能にドキュメントを添える
▶ 専用の書式で意味付けできる
▶ ソースコードとプレイグラウンドの 
両方で使用できる
▶ クイックヘルプやコード補完で見れる
特徴
シンボルの文書化

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

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

▶ コード補完
表示
▶ クイックヘルプ

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

▶ コメント行内でマークアップする
▶ コメント行は次の２通りで書く
(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] を使います。
//: 以上
記載例

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) を使えます。
記載例

記号のエスケープ

テキスト
▶ 特別な記号をそのまま表示できる
記載方法
記号
テキスト

//: 次のように書くとリンクを挿入できます。
//:
//: [タイトル](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 ページのリソース
このページ 
専用
全ページで
使える

ページ作成

▶ プロジェクトナビゲーターから作成
ページの新規作成
新規作成
⌥ + Click

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

ページ移動

ページ移動
//: 目次
//:
//: [セクション A](Section%20A)
//:
//: [セクション B](Section%20B)
表示例
記載例

ページ移動
//: [前のページ](@previous)
//:
//: [次のページ](@next)
表示例
記載例

▶ シンボルに説明を記載できる
• セクションで詳しく意味づけできる
• コード補完やクイックヘルプで見れる
• テキストを装飾できる
▶ Playground コメントの可能性が広がる
• テキストを装飾できる
• ページ移動のリンクが貼れる
まとめ

▶ コメントの書き方
▶ 強化されたドキュメントコメント
▶ シンボルの文書化
▶ リッチコメント
▶ マークアップ
▶ 行書式コマンド
▶ テキスト書式コマンド
▶ シンボル文書化コマンド
▶ ページナビゲーションコマンド
Xcode 7 + Swift 2

おまけ

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

HTML タグを混ぜられる？
説明の中で
HTML を使うと

クイックヘルプ
に反映される
HTML タグを混ぜられる？

スタイルシートも混ぜられる？
スタイルを
説明に添えると

に反映される
スタイルシートも混ぜられる？

スタイル指定はお勧めできない？
▶ コメント毎にスタイルが必要
▶ コメントの度に本格的なスタイルを 
記載するのは非現実的
▶ 見た目の統一性がなくなる
▶ そもそも正式に使える機能か判らない

もしかして
JavaScript が使える？

JavaScript を混ぜられる？
で実行される
説明の中で
script を使うと

JavaScript を混ぜられる？
コード補完だと 
バレバレ
▶ ただしコード補完では 
スクリプトがそのまま表示される

JavaScript 埋め込みはお勧めできない？
▶ 正式に使える機能か判らない
▶ コード補完でコードがそのまま表示される
▶ そもそもそこまで必要なのか？

Swift ドキュメントコメント

More Related Content

What's hot

Viewers also liked

Similar to Swift ドキュメントコメント

More from Tomohiro Kumagai

Recently uploaded

Swift ドキュメントコメント