SwiftUIなどドキュメントとツールを再確認

iOSなどの開発資料は英語が中心ですが、必要不可欠です。
膨大な資料の中から自分に必要なものを効率よく見つけ出しましょう。
webページだけでなくDeveloperアプリとXcode・PlaygroundsアプリのDocumentation表示の使いこなしを解説します。

▪︎このnoteはiOSアプリ開発関連記事です
▪︎Swiftはプログラミング言語です　車ではありません

ドキュメント　
ここでは「Documentation」の省略的に使っています。
技術資料のことで、印刷物だけでなくオンラインの文書やスライドやビデオなども含みます。
現在では辞書にコンピューター関連用語のひとつとして載っている場合もあるようです。

1　『こんなドキュメントがあったのか』体験

iOSアプリ開発の概要を解説したドキュメントはなくなったのか？とずっと感じつつあきらめていた資料を偶然見つけることがありました。
ドキュメントを表示する手段はいくつもありますが、少し慣れてくると同じ使い方になってしまいがちで見落としていただけのようです。

今回はドキュメント（開発資料）をどのようにして見つけ出すかを改めて検討し、いろいろ試したり探したりした結果も含め使いこなしなどと共にご紹介します。

この記事は現在アプリ開発中の人はもちろん、これから開発してみたい人にもお役にたつはずです。

お知らせ
プログラミング未経験者向けの電子書籍をAppleのブックストアから出しています。
未経験者のための『コードを学ぼう』ガイド （サンプルは無料です）
Swift5.3対応済みの Swift5初級ガイド （サンプルは無料です）もブックストアから出しています。
noteの記事『iOSアプリを作ろう・開発に必要な知識』（有料記事ですがおよそ半分試読できます）も参考にどうぞ。

・・・

1-1　Apple公式の開発情報

webの公式開発情報としてDeveloperサイトがあります。
Developerサイトは英語ですがほぼ同じの内容を日本語で表示する日本語Developerサイトもあります。
オフラインで参照できるものにはXcodeのドキュメントやPlaygroundsアプリのドキュメントがあります。
文字だけではなくビデオも含めた開発情報を得るツールとしてDeveloperアプリがあり、この使いこなしも効率の良い情報収集には重要となりそうです。
順にご紹介します。

1-2　開発情報の特徴

Appleに限らないと思いますがつぎのような特徴があります：
▪︎公式情報だけでも膨大なページ数がある
▪︎階層も深い
▪︎基本的に英語で書かれている
▪︎毎年追加や更新がある（不定期の追加情報もある）

とても情報量が多いのです。
幸いすべてに精通していなくてもアプリ開発は可能です。
すべてを完璧に理解する必要はまったくありません。安心してください。
まずは概要をつかみ、必要な時に必要な部分だけ参照すれば良いのです。
徐々に理解できる範囲を広げていきましょう。

1-3　ドキュメントについて

アプリ開発に必要な資料（ドキュメント）についてはこちらのnoteに書きました。

（2019年3月に書いた記事ですが、これまでに二度見直し加筆しています）

iOS関連のドキュメントは基本英語で書かれているので、そこで尻込みしてしまう方も多いかと思います。

私も英語は苦手です。
私がMacの開発をはじめた当初は英語の資料しかなくとても苦労しました。
ドキュメントは英語ですが、決まった形式で書かれていてポイントを押さえて取り組むことで、無駄を避けることができます。

それをお伝えするために上記の『iOSアプリを作ろう・資料の探し方読み方』を書きました。
少しでも効率よく情報収集するテクニックを身につけてください。

今回はこの記事の最新の補足を兼ねwebページだけでなくアプリの使いこなしなどを解説することにしました。

1-4　最新情報とのつきあい

技術情報は変化が激しいです。
現在Apple公式の資料でも macOS 11.0 関連はBeta扱いです。

Beta（β）
登録開発者だけが試すことのできる新バージョンをギリシャ文字の α β のベータで示すのが慣例です。
正式リリース時には一部変更になる可能性を含んでいます。
Betaの段階では詳しい説明が書かれていない場合も少なくありません。
基本的にOSと開発ツールを両方もBeta版にしなければ試せません。

2020年10月現在はiOS 14やwatchOS 7 は正式版になりましたが、WWDC2020後の6月から9月はBeta扱いでした。

ドキュメントにはBetaを明記してあるので、見落とさないようにしてください。

1-5　Swiftでこんな資料があったのか！

この記事のために調べていて気づきました。
Swift登場前からObjective-Cで開発していた人には常識でも、iOSなどの開発を始めたばかりの人には重要な情報です。

特にiOS13あるいはそれ以前もサポート必要などの条件があるとUIKitやAppKitを使いこなさなければなりません。
その場合に避けて通れないことが英文ですが資料としてまとまっていました。

Cocoa Design Patterns　
Swift専用のドキュメントです。
アプリ作りに欠かせないCocoaのデザインパターンを解説する5つの記事にリンクしたページです。

Using Objective-C Runtime Features in Swift　
Swiftで書いていてもObjective-C時代に作られたフレームワークを使うのに必要となる対応などが書かれています。

Imported C and Objective-C APIs　
Swiftから C や Objective-C で書かれたライブラリーなどを使う場合の情報へリンクしたページです。

他にもありましたので『Swift』フレームワークのページからリンクをたどってみてください。

資料はあっても『やはり、英語は苦手』の場合は『iOSアプリを作ろう・資料の探し方読み方』を参考に注目ポイントを押さえつつ、本文はGoogle翻訳やDeepLなど好みの翻訳ツールを使ってみてください。
翻訳結果の意味が不明確な場合は別のツールの訳と比べるのが有効です。

ただし翻訳ツールもまだまだ発展途上です。
長文で節の訳がまるごと抜けていたり、用語とみなされ訳文に英単語がそのまま表示されていると思ったらスペルが変わっていた　などの現象を私も体験しています。

1-6　SwiftUIの追加された資料

『SwiftUIのデータフローその3』にも書きましたがWWDC2020以降に複数の資料が追加になりました。

「State and Data Flow」「Managing User Interface State」「Managing Model Data in Your App」です。
それぞれの概要は『SwiftUIのデータフローその3』の　1 SwiftUIのドキュメント　を参照してください。
なおこれらの資料にはiOS 14など最新環境でしか使えない機能も紹介されているのでご注意ください。

追加になった資料には特にマークなどはなく、日付もないので追加されたことは気づきにくい状態です。

1-7　Xcode関連資料

私は完全に見落としていましたが、Xcode関連の資料もありました。

Creating an Xcode Project for an App　

Creating Your App's Interface with SwiftUI　

Supporting Dark Mode in Your Interface　

初級向けとは言えませんがDebuggingやPerformance関連などほかにもいろいろあります。

2　Developerサイト

一番の情報源はやはり本家AppleのDeveloperサイトです。
URLは「https://developer.apple.com」です。

右上の虫眼鏡ボタンで検索できます。

一番下に表示言語を選ぶメニューがあります。

ここで日本語の内容を表示できます。
対応する日本語のページがない場合は日本語のトップページを表示します。

Developerサイトの一番下には各タブで表示するリンクが並びます。
たとえば Develop タブの Downloads などへジャンプできます。

To view the latest developer news, visit News and Updates. から「News and Updates」も表示できます。

基本的には英語表示の本家のサイトが最新で充実しています。
ここ数年で日本語のページもかなり増えてきました。

2-1　Documentation ページ

DeveloperサイトのDocumentation ページ（Developタブの Documentation）にはフレームワーク別に詳細な資料があります。URLは「https://developer.apple.com/documentation/」です。

Documentation ページは「Featured」と「Technologies」タブがあります。
この「Featured」には最新の（Appleオススメの）技術へリンクしています。

Appleオススメ技術をいち早く取り入れたアプリはApp Storeで露出がふえるチャンスがあります。

「Technologies」タブはフレームワークなどに分類されています。

検索で絞り込むようになっていますが、絞り込み前の数が235となっています。
ここでの絞り込みはフレームワーク名などです。
実際の型やドキュメントの名称はDeveloperサイトの検索機能を使って探します。

ABC順にならんでいます、スクロールして目的のフレームワークなどを表示もできますが、これだけ膨大だと順に見ていくのは現実的ではありません。

カテゴリー別に絞り込む　
入力欄（Filter on this page）をクリックするとすぐ下にカテゴリーを表示します。
カテゴリーの候補は左右にスクロールできます。
入力欄に何も入力していないとカテゴリーは大分類※になり、入力がある場合は入力に関連するカテゴリーの候補を表示します。
（※大分類はXcodeのドキュメントなどでも使われています）

カテゴリーをクリックするとそのカテゴリーが入力され、さらにキーワードをタイプして絞り込みができます。
次画面のようにさらに別のカテゴリーを表示する場合もあります。

入力欄にあるカテゴリー（上記ではDesign）はクリックで選択しdeleteキーで削除できます。

追加変更などの確認　
オンラインのDeveloperサイトでは新OSでの追加や変更などSDKのバージョンによる違い（Xcodeバージョンによる違い）は確認できます。
「Show API Changes」でXcodeのバージョンで選ぶことができます。

こうすると今後変更の予定されている資料だけに絞り込みます。

各型などのページではAPI Changes: で「Show」を選ぶと変更のある部分に〜Modified（変更あり）、＋Added（追加）、−Deprecated（新たに非推奨になった）アイコンを表示します。

各ページのヘッダの表示情報や使い方などは『iOSアプリを作ろう・資料の探し方読み方』の　Documentation ページのヘッダ、変更点の確認、プログラミング言語選択、Documentation ページ共通情報、利用可能なOS範囲　などを参照してください。

型名やメソッド名などでの検索は同じく『iOSアプリを作ろう・資料の探し方読み方』の　ドキュメントの検索、検索結果の絞り込み　を参照してください。

現在「button」などの一般的な単語で検索してもSwiftUIの型が上位に表示されます。

2-2　概要記事 Article

「資料の探し方読み方」でも紹介しましたが、公式ドキュメントにはアイコンが付いていてArticleなどの種類が区別できます。

たとえば「SwiftUIとCombineフレームワークその1」では次のArticleを紹介しました。
2︎⃣Receiving and Handling Events with Combine（英文）
3︎⃣Controlling Publishing with Connectable Publishers（英文）
4︎⃣Processing Published Elements with Subscribers（英文）
5︎⃣Routing Notifications to Combine Subscribers（英文）
6︎⃣Replacing Foundation Timers with Timer Publishers（英文）
7︎⃣Performing Key-Value Observing with Combine（英文）
8︎⃣Using Combine for Your App’s Asynchronous Code（英文）

未知の分野の概要情報を伝えてくれるArticleは（英文ではありますが）開発にとても重要です。
これらのドキュメントは 1︎⃣Combineフレームワークのページからリンクしています。

2︎⃣から8︎⃣は有効な情報ですが、このようなArticleが存在することが 1︎⃣Combineフレームワークのページを開かなければ気付くことができないのが問題です。
【この問題の対策については　7-1 Articleを探す　で説明します】

文字の情報だけでなくビデオも充実しています。
なおビデオの視聴は後で紹介するDeveloperアプリが便利です。

注意：ArticleにはAPI ChangesやOSバージョン表記がありません

ArticleにはBeta版を含む最新のSDKや型の情報が注記なしに混在している場合があります。

2-3　Developerアプリと連携

概要情報としてのビデオ　
WWDCをはじめとする日本語字幕付き解説ビデオも概要をつかむための情報として有効です。

webブラウザーでビデオを視聴する場合は『iOSアプリを作ろう・資料の探し方読み方』の　公式ビデオ、検索と分野・OSでの絞り込み、ビデオ画面の操作ボタン、字幕と Transcript を活用しよう、ビデオとスライドのダウンロード　も参照してください。

WebのDeveloperサイトを表示するとつぎのような「"Developer"アプリケーションで開く」と表示されることがあります。
この状態で右側の「開く」ボタンをクリックするとDeveloperアプリで対応するコンテンツやページを開きます。

この画面はWWDCビデオですが、ニュースなどでも連携できます。

3　日本語DeveloperサイトとDocumentationページ

ここでは言語を日本語に切り替えた状態を日本語のDeveloperサイトと呼ぶことにします。
URLは「https://developer.apple.com/jp/」です。

英語のDeveloperサイトと同じ構成で日本語に翻訳した内容が読めます。
ただしすべてが翻訳されているとは限りません。
英語サイトの内容が更新されてから日本語に翻訳されてこのページに載るまで時間がかかる場合もあります。
日本ではまだ提供されていない機能などの情報は翻訳されていない場合が多いようです。

3-1　充実してきた日本語開発情報

Developer登録手続きやアプリの申請関連の情報は日本語ページもかなり充実してきました（とても助かります）。
「見つける」「デザイン」「開発」「配信」「サポート」各タブの隅々までチェックしてください。（日本語の情報量もけっこう多いです）
Xcodeのページも最新のXcode 12の内容に更新されています。

日本語に翻訳済みのドキュメントもありますが、残念ながらフレームワークなどの一部に限られます。
元になる英語版が更新されても翻訳が更新されるまで時間がかかる傾向です。

一方Developerアプリでも確認できるニュースとアップデートなどは日本語での提供が増えてきています。
webブラウザーでこのページは日本語に翻訳済みの情報のみ掲載されます、英語サイトの「News and Updates」だけに載る情報もあります。

3-2　オンラインドキュメントの特徴

（日本語版に限らず）Developerサイトなどオンラインの資料の特徴です：

○ 手軽に参照できる
○ 最新の内容（特に型とそののメソッドやプロパティ類）でDeprecatedも明示されている
○ 翻訳ツールも使いやすい
○ 検索できる

❌ 変更点を確認しにくい
❌ 変更に気づかない【必要な情報を見落としてしまう】
❌ 過去の資料にアクセスできない【予告なく消えてしまった場合はアクセス不能になる】

変更に気がつきにくいのは、かなり困った問題です。
仕様変更などは明示されるので良いのですが、解説が詳しくなるなどの開発者にとってうれしい追加もあります。
解説の追加はそのページを開かないと確認できず、目立たないために見落とすこともあります。
追加変更前と簡単には比較できないので追加に気付きにくいのもオンライン資料の特徴です。

タイトルが同じだと「既に見た」と思い込みがちです。
開いて読んでみると追加の内容があるのにスルーしてしまうのはもったいないです。

【追加に気づかない問題の私なりの対処方法は　7-2 ドキュメントを比較し追加などを見つける　で説明します】

3-3　PDFなどの資料

現在は少ないですが、かつてはPDFでダウンロード可能な資料も多く提供されていました。
PDFダウンロードボタンがありWebでもPDFでも読めるものと、PDFだけで提供されるものがありました。
日本語に翻訳された資料はPDFで提供されたものが多かった印象です。

かつて（1990年前後）は資料が印刷物からPDFをCDで配布に変わりました。
その後WebでもPDFがダウンロード可能になり、CDでの配布がなくなりオンラインの資料が中心になりました。

アーカイブに古い資料が残っています（PDFのリンクはざっと見た範囲では残っていませんでした）。

Documentation Archive

このアーカイブ（昔のDeveloperドキュメントサイト）は「Articles」「Getting Started」「Guides」などの分類も可能だったので使い勝手が良かったです。
現在提供されているオンラインドキュメントでは「Articles」だけの一覧がほしくてもみることはできません。
一覧があれば追加にも気付くことができるのですが。

PDFで提供される資料の特徴

○ダウンロードできる
○公開中止になっても手元に残る
○オフラインでも参照できる
○ドキュメントの中だけ限定で検索できる
○違う版を比較できる
❌容量が比較的大きい

2019年までWWDCのセッションスライドはPDFでダウンロード可能でした。
WWDC2020では残念ながらスライドPDFは公開されていません。

PDFの書類内で検索は便利でした。
Webもページ内の検索は可能ですが、Human Interface Guidelines のようなページ数の多い資料は全体を効率良く検索したくなります。

4　Xcodeのドキュメント

Xcodeの Window > Developer Documentation メニューはDeveloperサイトのドキュメントとほぼ同じ内容ですがすべてXcodeに内蔵しオフラインで表示可能です。
（サンプルダウンロードやビデオなどにはネット接続が必要です。）
（Xcode 12でFeatured画面も追加になりました）
表示ショートカットは⇧⌘0（シフト＋コマンド+ゼロ）です。

内蔵しているため、そのXcodeのSDKと同じバージョンのドキュメントだけを表示します。
つまり古いXcode 11.xのDocumentationウインドウには新しいフレームワークや型は載っていません、また新しいXcodeでDeprecatedになるものは確認できないのでその点はwebで確認するなど注意が必要です。

みつけたページを共有したり、別のタブで開いたままにすることもできます。