ドキュメントの機能と活用方法

Xcode には、英語ですがとても詳しいドキュメントが用意されています。API リファレンスから、プログラミングガイド、サンプルプロジェクトなども収録されていて、Xcode からだけでも多くのドキュメントを見つけられます。

ドキュメントを閲覧する

それでは、表示されたドキュメントのどの辺りを読むといいかを見ていきましょう。

ドキュメントのアウトラインを参照する

開いているドキュメントのセクション構成は、コンテンツ一覧の画面で確認できます。

ツールバーの左側にあるコンテンツ一覧アイコンをクリックすると、表示中のドキュメントのアウトラインが、ドキュメントの左側に表示されます。

ここで、このドキュメントがどういった構成になっているかを確認できます。そして、気になるところをクリックすれば、その位置まで移動できます。

ドキュメントによっては、アウトラインの情報がない場合があります。その場合はこの領域にNo Contentsと表示されます。

API リファレンスを読む

アプリの制作を進める中で、頻繁に目を通すことになるのがAPI リファレンスです。そこで、API リファレンスでよく目にするドキュメントの書かれ方について簡単に紹介します。

たとえばNSStringクラスのstringByReplacingPercentEscapesUsingEncoding:というメソッドをドキュメントで調べたときには、そのメソッドが含まれるNSString全体のドキュメントが表示されています。このような場面で、ドキュメントのどの辺りに何が記されているかを見ていきます。

メソッドの概要

メソッド名で検索をかけると、たどり着くのがそのメソッドの説明ページです。

今回の場合はこのメソッドを知るのが目的なので、ここを見ればおおよそのことが分かります。ここで注目したい箇所は次の辺りになります。

まずは、冒頭にあるメソッドの概要です。とりあえず何をするメソッドなのかを知りたいときには、ここに目を通してみると良いでしょう。

そして、このメソッドの定義です。

たとえばメソッドの役割は分かるけれど、引数や戻り値の型が分からないようなときに、ここを見れば足りることもよくあります。なお、ここでは引数の型がリンクになっていることが多く、その場合はその型のドキュメントをすぐにたどれます。

これだけでは情報が足りない場合は、その下にさらに詳しい情報が記されています。その中で次のものを見る機会が多いです。

ラベル	内容
`Parameters`	このメソッドにどのような引数を渡せば良いかが、引数名毎に詳しく説明されています。引数に`nil`を渡すとどうなるかなど、注意事項が記されている場合もあります。
`Return Value`	このメソッドがどのような戻り値を返すかが詳しく説明されています。どのような状況で`nil`を返す場合があるかなども記されていることがあります。
`Availability`	このメソッドがどのバージョンから利用可能になったかが記されています。たとえば`Available in iOS 2.0 and later`なら、iOS 2.0 以上からこのメソッドが利用できることを意味しています。また、メソッドが途中で廃止された場合、たとえば iOS 6.0 で廃止された場合は、ここに`Deprecated in 6.0`という記載が併記されています。
`Declared In`	このメソッドが定義されているヘッダーファイルが記されています。このメソッドを使いたいのに`#import`が不足している場合に、このファイルを指定することで利用できる場合があります。

廃止されたメソッドについて

API の機能の中には OS のバージョンアップとともに廃止されるものがあります。ドキュメント内では、廃止された機能についても分かるようになっています。

記されているのは、特に 2 箇所で、その中でも冒頭では赤く目立つ表記がされています。ここで記されているバージョンから、このメソッドが利用できなくなっています。

それと合わせて、それに代わる機能が提供されている場合には、冒頭の文の最後の辺りでUse ***** instead.と記されています。代わりになる機能の表記にはリンクが貼られているので、そこからその機能の説明へとたどれます。

メソッドの説明がほとんど終わった辺りにあるAvailabilityにもDeprecated inという表記で、どのバージョンから使えなくなったかが記されています。先にこちらの表記に気がついた場合は、このメソッドの冒頭にある説明文を見てみると、代わりになるメソッドが紹介されているかもしれません。

そのクラス全体の概要を確認する

クラス名からドキュメントをたどった時は、もちろんそのクラスの説明ページが表示されますが、メソッド名でドキュメントをたどって開いたときも、それが所属するクラスのページが開かれています。

このページの冒頭にはクラスに関する概要がまとめられています。ここを見ることで、そのクラスがどのような造りになっているかを確認できます。

さらにここのMore related items...を選択すると、このクラスが定義されているファイルや、このクラスを使ったサンプルコードなどを確認できます。

ラベル	内容
`Inherits from`	このクラスがどのクラスを継承しているかが記載されています。そのクラスのドキュメントをリンクからたどれます。
`Conforms to`	このクラスがどのプロトコルに準拠しているかが記されています。それらのプロトコルのドキュメントをリンクからたどれます。
`Framework`	このクラスがどのフレームワークに属しているかが記されています。
`Availability`	このメソッドがどのバージョンから利用可能になったかが記されています。
`Declared in`	このクラスが定義されているヘッダーファイルが記されています。
`Related documents`	このクラスに関係するドキュメントが記されています。ここからリンクをたどってドキュメントを閲覧できます。
`Sample code`	このクラスが関係するサンプルコードが掲載されたドキュメントが記されています。ここからリンクをたどってドキュメントを閲覧できます。

そして、冒頭に続く本文内のOverviewでは、このクラスがどのような目的で実装されているかを確認できます。

それ以降は、おおよそ次のセクションに注意しながら読み進めると、ドキュメントの内容を把握しやすくなります。

ラベル	内容
`Tasks`	クラスが持っている機能が、用途毎に整理してリストアップされています。このクラスがどんな機能を持っているかや、その機能に関係するプロパティーやメソッドを把握するのに便利です。気になった項目は、リンクをたどってすぐに詳細を確認できます。
`Properties`	このセクションでは、クラスに実装されているプロパティーの詳細説明が行われます。
`Class Methods`	このセクションでは、クラスに実装されているクラスメソッドの詳細説明が行われます。
`Instance Methods`	このセクションでは、クラスに実装されているインスタンスメソッドの詳細説明が行われます。
`Constants`	このセクションでは、クラスに関係する定数や列挙子などの用途が詳しく説明されます。
`Notifications`	このセクションでは、クラスが送信する通知の名前とその詳細情報が説明されます。この通知は`NSNotificationCenter`を通してやり取りされます。

サンプルコードを Xcode で開く

ドキュメントをたどっていると、それに関係するサンプルコードが提供されていることがあります。

サンプルコードのページを開くと、サンプルコードの目的と実行環境の条件などが表示されます。そして、この画面の左上にあるOpen Projectをクリックすると、サンプルコードをダウンロードして Xcode で開けます。

ダウンロードしたソースコードは Mac のダウンロードフォルダーに保存され、自動的に Xcode で開かれます。

サンプルコードを探す

サンプルコードは、ドキュメントのさまざまなところから見つけられます。たとえば API リファレンス内なら、冒頭のMore related items...や、各メソッドなどの説明にあるRelated Sample Codeからたどれます。

ドキュメントライブラリからであれば、各セクション内にあるSample Codeから探せます。

また、ドキュメント全体での検索でも候補に挙がってくることがあります。