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

200 Views

November 05, 15

#swift #Xcode 7 #Swift 2 #ドキュメントコメント #Swift開発 #プログラミング

スライド概要

2015-11-05 に開催された『iOS 9 週連続 Bootcamp!』の第６回目で Xcode 7 の新機能について紹介 (http://www.slideshare.net/tomohirokumagai54/xcode-7-cmios9) してきた中で、時間の都合でカットしたドキュメントコメントの内容です。

※ Docswell での公開に移行する直前の Slideshare での閲覧数は 5,325 でした。

熊谷友宏

@es_kumagai

スライド一覧

正統派趣味人プログラマー。プログラミングとは幼馴染です。

またはPlayer版

埋め込む »CMSなどでJSが使えない場合

ダウンロード

ダウンロード(pdf - 17.07MB)

関連スライド

Swift Concurrency 要諦 #ゆるちとせ

swift 並行処理千歳ゆるい勉強会

熊谷友宏 3.5K

プロトコル指向に想う世界観 #swift

swift愛好会 swift プロトコル指向

熊谷友宏 1.4K

#関モバ Swift Concurrency 要諦

swift 並行処理関モバ

熊谷友宏 681

値付き Enum 入門、そして伝説へ #yhios #cocoa kansai

swift 横浜へなちょこ勉強会 cocoa関西

熊谷友宏 391

Xcode グループとフォルダー参照 #yhios

yidev xcode 横浜へなちょこ勉強会

熊谷友宏 382

DTMF — DTMF と自作アプリの軌跡 #yidev

objective-c ios dtmf オーディオ yidev

熊谷友宏 380

各ページのテキスト

Xcode 7 & Swift 2 ドキュメントコメント 2015.11.02 EZ-NET 熊⾕友宏 http://ez-net.jp/

http://ez-net.jp/

熊谷友宏 EZ-NET http://ez-net.jp/ @es̲kumagai iOS, OS X, Apple Watch アプリ CodePiece いつもの電卓ソースコードを Twitter と Gist に同時投稿できる。計算式も見える電卓アプリ。 watchOS 1 対応音で再配達ゴッド EZ-NET IP Phone 簡単操作で再配達の申し込み。 iPhone でひかり電話を使う。自宅 LAN からの利用専用

http://ez-net.jp/

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

http://ez-net.jp/

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

著書 Xcode 5 徹底解説 > 全機能を徹底解説 ✔ ✔ ✔ ✔ ✔ 各画面の使い方プロジェクトやコードの編集インターフェイスビルダービルドとデバッグユニットテストと Bot > 紙版は絶版 (2015/08/21) 750 ページ 2014/04/28 - 2015/08/21 > 電子書籍版は販売中 ✔ 10x-Eng.com でも取扱予定

MSM 2015 Swift 2 の話をする予定 > MSM 2015 ✔ ✔ ✔ ✔ 2015/11/06 - 2015/11/07 http://www.mosa.gr.jp/ NPO 法人 MOSA 主催有料イベント（会員制）年に一度の２日間に渡るお祭り的なイベント Apple 最新技術の話題満載 > NPO 法人 MOSA ✔ ✔ 10 年以上の活動実績法人会員での参加も多い印象

http://www.mosa.gr.jp/

Xcode 7 ̶ 2015.09.16 ̶

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

ドキュメントコメント

10.

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

11.

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

12.

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

13.

1. シンボルの文書化

14.

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

15.

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

16.

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

17.

シンボルの文書化表示 ▶ コード補完 ▶ クイックヘルプ

18.

2. リッチコメント

19.

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

20.

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

21.

リッチコメント記載 //: ## ̀reducè メソッド //: 配列の **総和** を簡単に計算できます。 //: ### 準備 let values = [1, 3, 8, 20] //: ### 実行 let sum = values.reduce(0, combine: +)

22.

リッチコメント表示

23.

リッチコメント表示の切り替え ▶ ファイルインスペクターで切り替えるオン・オフで切り替わる

24.

リッチコメント留意点 ▶ リッチコメント表示中でも • 実行コードを編集できる ▶ リッチコメント表示中は • リッチコメントを編集できない • 通常のコメントは編集できる

25.

マークアップ

26.

マークアップ基本 ▶ シンボルの文書化やリッチコメントの内容に付加情報を添える ▶ コマンドを使ってマークアップする ▶ コマンドはインデントレベルが大事 • インデントによって解釈が変わる • コメントブロックの最初が第一レベル ▶ Markdown みたいな書式

27.

マークアップコマンドの種類 1. 行書式コマンド 2. テキスト書式コマンドシンボル文書化専用 3. シンボル文書化コマンド 4. ページナビゲーションコマンドリッチコメント専用

28.

1. 行書式コマンドシンボル文書化リッチコメント

29.

行書式コマンド特徴 ▶ 行単位で書式を指定する基本書式行書式コマンド行テキスト空白必須シンボル文書化リッチコメント

30.

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

31.

行書式コマンド見出しシンボル文書化リッチコメント

32.

行書式コマンド見出し ▶ 行を見出しとして扱う ▶ 先頭の # の数でレベルを指定（３レベルまで）記載方法空白必須 # 最初の見出しです。 ## 次の見出しです。記号の数でレベル指定シンボル文書化リッチコメント

33.

行書式コマンド見出し記載例 //: 見出しを表示します。 //: # 最初の見出しです。 //: ## 次の見出しです。 //: 以上表示例（リッチコメント）シンボル文書化リッチコメント

34.

行書式コマンド見出し（別の書き方）見出しを次行の下線で表現する ▶ = = = で表現する • レベル１は • レベル２は --- で表現する記載方法 ↩ 最初は空行見出しです。＝＝＝＝＝＝２行目で下線を表現シンボル文書化リッチコメント

35.

行書式コマンド見出し記載例 //: 見出しを表示します。 //: //: 見出しです。 //: =========== //: 以上表示例（リッチコメント）シンボル文書化リッチコメント

36.

行書式コマンドブロック引用シンボル文書化リッチコメント

37.

行書式コマンドブロック引用 ▶ 内容を引用として扱う ▶ 連続で書くと１つとして扱われる記載方法 > 引用してきたテキストを記載します。 > 複数行に分けて続きを記載できます。 ↩ 空白必須最後は空行シンボル文書化リッチコメント

38.

行書式コマンドブロック引用記載例 //: 次のような説明が記載されています。 //: //: > 引用してきたテキストを記載します。 //: > 複数行に分けて続きを記載できます。 //: //: 以上表示例（リッチコメント）シンボル文書化リッチコメント

39.

行書式コマンド箇条書きシンボル文書化リッチコメント

40.

行書式コマンド箇条書き ▶ 先頭は *, +, - のどれかで揃える ▶ 同レベルの項目は同じインデントで書く記載方法インデントを揃える * 最初の項目 * ふたつ目の項目空白必須 ↩ 最後は空行 * ふたつ目にぶら下げた項目レベルを変えられるシンボル文書化リッチコメント

41.

行書式コマンド箇条書き記載例 //: 項目を箇条書きします。 //: * 最初の項目 //: * ふたつ目の項目 //: * ふたつ目にぶら下げた項目 //: //: 以上表示例（リッチコメント）シンボル文書化リッチコメント

42.

行書式コマンド番号付き箇条書きシンボル文書化リッチコメント

43.

行書式コマンド番号付き箇条書き ▶ 先頭を番号と .で始める ▶ どんな番号でも連番に振り直される記載方法インデントを揃える 1 . 最初の項目 1 . ふたつ目の項目 1 ↩ 最後は空行 . レベルを変えられるぶら下げた項目シンボル文書化リッチコメント

44.

行書式コマンド番号付き箇条書き記載例 //: 項目を箇条書きします。 //: 1. 最初の項目 //: 1. ふたつ目の項目 //: 1. ふたつ目にぶら下げた項目 //: //: 以上表示例（リッチコメント）シンボル文書化リッチコメント

45.

行書式コマンド番号付き箇条書き採番のされ方が異なる //: 3. 最初の項目 //: 3. ふたつ目の項目表示例シンボル文書化は１番からリッチコメントは指定番号からシンボル文書化リッチコメント

46.

行書式コマンドコードブロックシンボル文書化リッチコメント

47.

行書式コマンドコードブロック ▶ 内容をプログラムコードとして扱う ▶ インデントして内容を記載する記載方法 ↩ 最初は空行 let 数値列 = [1, 3, 5, 7] let 総和 = 数値列.reduce(0, combine: +) ↩ インデント必須最後は空行シンボル文書化リッチコメント

48.

行書式コマンドコードブロック（別の書き方） ▶ 上下を ̀̀̀ で括って書ける ▶ シンボル文書化だけで使える記載方法 ̀̀̀ インデント不要 let 数値列 = [1, 3, 5, 7] let 総和 = 数値列.reduce(0, combine: +) ̀̀̀ 空行不要シンボル文書化リッチコメント

49.

行書式コマンドコードブロック記載例 //: サンプルコードです。 //: //: let 数値列 = [1, 3, 5, 7] //: let 総和 = 数値列.reduce(0, combine: +) //: //: 以上表示例（リッチコメント）シンボル文書化リッチコメント

50.

行書式コマンド水平線シンボル文書化リッチコメント

51.

行書式コマンド水平線 ▶ 行を水平線にする ▶ ３文字以上のハイフンで表現する記載方法 ↩ 最初は空行 −−− ↩ ３文字以上最後は空行シンボル文書化リッチコメント

52.

行書式コマンド水平線記載例 //: 水平線で分断します。 //: //: - - //: //: 以上表示例（リッチコメント）シンボル文書化リッチコメント

53.

行書式コマンドリンク参照シンボル文書化リッチコメント

54.

行書式コマンドリンク参照 ▶ リンク付きテキストを定義する ▶ 定義後に本文内でテキストを使う記載方法必要に応じて最初は改行 ↩ [ テキスト ] 定義したテキスト URL " [ テキストホバーテキスト ] シンボル文書化 " を使うリッチコメント

55.

行書式コマンドリンク参照記載例 //: テキストにリンクを定義して使います。 //: //: [EZ-NET]: http://ez-net.jp "EZ-NET" //: 定義したテキスト [EZ-NET] を使います。 //: 以上表示例（リッチコメント）シンボル文書化リッチコメント

http://ez-net.jp

56.

2. テキスト書式コマンドシンボル文書化リッチコメント

57.

テキスト書式コマンド特徴 ▶ 文字列単位で書式を指定する基本書式テキストコマンドテキストコマンドシンボル文書化テキストリッチコメント

58.

テキスト書式コマンド種類 ▶ 強調表記 ▶ コード表記 ▶ 画像表記 ▶ リンク参照 ▶ 記号のエスケープ

59.

テキスト書式コマンド強調表記シンボル文書化リッチコメント

60.

テキスト書式コマンド強調表記 : 斜体 ▶ テキストを強調して表示する ▶ 両側を * または _ で括る記載方法 Swift には * 二種類の変数 * があります。目的の語句を囲うシンボル文書化リッチコメント

61.

テキスト書式コマンド強調表記 : 斜体記載例 //: テキストの一部を強調して表現します。 //: //: Swift には *二種類の変数* があります。表示例（リッチコメント）シンボル文書化リッチコメント

62.

テキスト書式コマンド強調表記 : 太字 ▶ テキストを強調して表示する ▶ 両側を ** または __ で括る記載方法 Swift はデータを ** 構造体 ** で表現します。シンボル文書化リッチコメント

63.

テキスト書式コマンド強調表記 : 太字記載例 //: テキストの一部を強調して表現します。 //: //: Swift ではデータを **構造体** で表現します。表示例（リッチコメント）シンボル文書化リッチコメント

64.

テキスト書式コマンド強調表記 : 太字と斜体 ▶ テキストを強調して表示する ▶ 両側を *** または ___ で括る記載方法構造体は *** 変数で振る舞いが変化シンボル文書化 *** します。リッチコメント

65.

テキスト書式コマンド強調表記 : 太字と斜体記載例 //: テキストの一部を強調して表現します。 //: //: 構造体は ***変数で振る舞いが変化*** します。表示例（リッチコメント）シンボル文書化リッチコメント

66.

テキスト書式コマンドコード表記シンボル文書化リッチコメント

67.

テキスト書式コマンドコード表記 ▶ テキストがコードであることを表現する ▶ 両側を ` で括る記載方法 Swift では原則 ̀ let ̀ で変数を扱います。シンボル文書化リッチコメント

68.

テキスト書式コマンドコード表記記載例 //: テキストの一部をコードとして表現します。 //: //: Swift では原則 ̀let̀ で変数を扱います。表示例（リッチコメント）シンボル文書化リッチコメント

69.

テキスト書式コマンド画像表記シンボル文書化リッチコメント

70.

テキスト書式コマンド画像表記 ▶ テキストに画像を挿入する ▶ 場面によって表現が変わる様子 • リッチコメントではブロック要素 • シンボル文書化ではインライン要素必要に応じて構文 ! [ 交代テキスト ] ( 画像パス " ポップアップシンボル文書化 " ) リッチコメント

71.

テキスト書式コマンド画像表記記載例 //: コメント内に画像を挿入します。 //: //: ![Note](https://ez-net.jp/note.png) Swift は //: 目まぐるしく進化します。表示例シンボル文書化はインラインリッチコメントはブロック扱いシンボル文書化リッチコメント

72.

テキスト書式コマンド画像サイズを変えたい時 ▶ HTML タグで画像を挿入する ▶ シンボルの文書化だけで使える様子 ▶ 正式な方法かは不明シンボル文書化リッチコメント

73.

テキスト書式コマンド画像サイズを変えたい時記載例 /// コメント内に画像を挿入します。 /// /// <img src="https://ez-net.jp/note.png" style="width: 14px”/> Swift は /// 目まぐるしく進化します。表示例（シンボル文書化）シンボル文書化リッチコメント

74.

テキスト書式コマンド画像のカレントパスシンボルの文書化リッチコメントシンボル文書化リッチコメント

75.

テキスト書式コマンドリンク参照シンボル文書化リッチコメント

76.

テキスト書式コマンドリンク参照 ▶ URL リンク付きのテキストを表現する ▶ テキスト内で自由に使える記載方法テキスト [ テキスト ] ( URL シンボル文書化 ) テキストリッチコメント

77.

テキスト書式コマンドリンク参照記載例 //: テキスト書式コマンドなら //: 事前定義なく [リンク](http://ez-net.jp) を使えます。表示例（リッチコメント）シンボル文書化リッチコメント

http://ez-net.jp

78.

テキスト書式コマンド記号のエスケープシンボル文書化リッチコメント

79.

テキスト書式コマンド記号のエスケープ ▶ 特別な記号をそのまま表示できる記載方法テキスト \ 記号テキストシンボル文書化リッチコメント

80.

テキスト書式コマンド記号のエスケープ記載例 //: 次のように書くとリンクを挿入できます。 //: //: \[タイトル](https://ez-net.jp) 表示例（リッチコメント）シンボル文書化リッチコメント

81.

3. シンボル文書化コマンドシンボル文書化リッチコメント

82.

シンボル文書化コマンド特徴 ▶ シンボルの説明に意味を添える ▶ ４つのセクションで構成される ▶ ハイフン記号で書き始める書式 - コマンド : コンテンツコンテンツの続きを次行に記載できる ↩ 最後は改行か別のコマンド必要に応じてシンボル文書化リッチコメント

83.

シンボル文書化コマンド４つのセクション 1. Description セクション 2. Parameters セクション 3. Returns セクション 4. Throws セクションシンボル文書化リッチコメント

84.

セクション Description シンボル文書化リッチコメント

85.

シンボル文書化コマンド Description セクション ▶ シンボルの説明を扱う ▶ コマンドを明記しないテキストが所属する ▶ 複数の Description フィールドを持てる基本書式コンテンツコマンドを含めずテキストを記載シンボル文書化リッチコメント

86.

シンボル文書化コマンド Description セクション記載例 /// 現在のターゲットを取得します。 var currentTarget:Target 表示例シンボル文書化リッチコメント

87.

シンボル文書化コマンド Description フィールド ▶ Description セクションに情報を添える ▶ いくつでも追加できる基本書式 - フィールド名 : 説明文説明文の続きを次行に記載できる ↩ 最後は改行か次のコマンド必要に応じてシンボル文書化リッチコメント

88.

シンボル文書化コマンド Description フィールド記載例 /// ストリームの末端まで読み進められているか調べます。 /// - precondition: ストリームが開かれている必要があります。 /// - note: 文字列ストリームでは NUL を末端とみなします。 func isEOF(stream:Stream) -> String { 表示例シンボル文書化リッチコメント

89.

シンボル文書化コマンド Description で使えるフィールド名 (1/4) - attention : 注目して欲しい情報を記載 - author : 著作者名 - bug : バグに関する情報を記載 - Complexity : アルゴリズム的な複雑さを記載 - copyright : 著作権に関する情報を記載 - date : 何らかの日付情報を記載 - experiment : 試験的な機能であることを記載シンボル文書化リッチコメント

90.

シンボル文書化コマンド Description で使えるフィールド名 (2/4) - important : 使用上の重要情報を記載 - invariant : 実行中に変化しないものを明記 - note : 補足情報を記載 - precondition : 実行に必要な値の前提条件を記載 - postcondition : 実行直後の値の変化を記載 - remark : シンボルの解説を記載シンボル文書化リッチコメント

91.

シンボル文書化コマンド Description で使えるフィールド名 (3/4) - requires : 実行に必要な環境情報を記載 - seealso : 別の参考資料を記載 - since : いつから使えるようになったかを記載 - todo : 実行完了に必要な追加タスクを記載 - version : シンボルのバージョン情報を記載 - warning : 使用上の注意事項を記載シンボル文書化リッチコメント

92.

シンボル文書化コマンド Description で使えるフィールド名 (4/4) ▶ 複数人数の著作者情報を記載基本書式 authors - : 著作者名 ↩ 改行で次の人著作者名 ↩ 最後は改行シンボル文書化リッチコメント

93.

セクション Parameters シンボル文書化リッチコメント

94.

シンボル文書化コマンド Parameters セクション ▶ シンボルの引数を扱う ▶ 複数のフィールドを持てる基本書式 - parameter 引数名 : 説明文説明文の続きを次行に記載できる ↩ 最後は改行か次のコマンド必要に応じてシンボル文書化リッチコメント

95.

シンボル文書化コマンド Parameters セクション記載例 /// ストリームに値を書き込みます。 /// - parameter value: 書き込む値です。 /// - parameter stream: 書き込み先のストリームです。 func write(value:String, stream:Stream) { 表示例シンボル文書化リッチコメント

96.

シンボル文書化コマンド Parameters の一括定義 ▶ 複数の引数情報を記載基本書式 - ↩ parameters : - 引数名 : 説明文 - 引数名 : 説明文インデント必須最後は改行か次のコマンドシンボル文書化リッチコメント

97.

シンボル文書化コマンド Parameters の一括定義記載例 /// ストリームに値を書き込みます。 /// - parameters: /// - value: 書き込む値です。 /// - stream: 書き込み先のストリームです。 func write(value:String, stream:Stream) { 表示例シンボル文書化リッチコメント

98.

セクション Returns シンボル文書化リッチコメント

99.

シンボル文書化コマンド Returns セクション ▶ シンボルの戻り値を扱う ▶ ひとつだけ指定できる基本書式 - returns : 説明文説明文の続きを次行に記載できる ↩ 最後は改行か次のコマンド必要に応じてシンボル文書化リッチコメント

100.

シンボル文書化コマンド Returns セクション記載例 /// ストリームから値を読み込みます。 /// - returns: 読み取った文字列を返します。 func read(stream:Stream) -> String { 表示例シンボル文書化リッチコメント

101.

セクション Throws シンボル文書化リッチコメント

102.

シンボル文書化コマンド Throws セクション ▶ エラーに関する情報を扱う ▶ ひとつだけ指定できる基本書式 - throws : 説明文説明文の続きを次行に記載できる ↩ 最後は改行か次のコマンド必要に応じてシンボル文書化リッチコメント

103.

シンボル文書化コマンド Throws セクション記載例 /// ストリームに値を書き込みます。 /// - throws: ストリームが開かれてないと /// Stream.NotOpenError が発生ます。 func write(value:String, stream:Stream) throws { 表示例シンボル文書化リッチコメント

104.

4. ページナビゲーションコマンドシンボル文書化リッチコメント

105.

ページナビゲーションコマンド特徴 ▶ ページ移動するための機能 • 指定ページに移動する • 前後のページに移動する ▶ リッチコメントだけで使えるシンボル文書化リッチコメント

106.

ページナビゲーションコマンド指定ページに移動 ▶ 指定したページ名へのリンクを作れる ▶ ページ名の空白文字は %20 に置き換える記載方法 [ 表題 ] ( 移動先ページ名シンボル文書化 ) リッチコメント

107.

ページナビゲーションコマンド次のページに移動 ▶ 次のページへのリンクを作れる ▶ 順番はプロジェクトナビゲーターで指定する記載方法 [ 表題 ] ( @next ) シンボル文書化リッチコメント

108.

ページナビゲーションコマンド前のページに移動 ▶ 前のページへのリンクを作れる ▶ 順番はプロジェクトナビゲーターで指定する記載方法 [ 表題 ] ( @previous ) シンボル文書化リッチコメント

109.

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