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 ドキュメントコメント

Recommended

Recommended

More Related Content

What's hot

What's hot (20)

Viewers also liked

Viewers also liked (7)

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

Similar to Swift ドキュメントコメント (20)

More from Tomohiro Kumagai

More from Tomohiro Kumagai (20)

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