ライブラリのリファレンスってどのように見ればよいのでしょうか？

最近、C++のライブラリでOpenGL、wxwidgets、fbxsdkなどを個人的に学習しているのですが、どうも効率が良くないような気がしていたので皆様がどのように学習をしているのかお聞かせいただければと思い質問させていただきました。

大学でOpenGL（1.5）を学習したときには、日本語の教科書を見ながら教授が１つ１つの関数について丁寧に説明してくれたので難なく学習できました。

しかし自分で学習をしてみると、自分でリファレンスを読んで理解していかないといけません。OpenGL（2.1）を学習したときは、購入した日本語版赤本のおかげでだいぶはかどりました（床井先生のサイトも助けになりました）。また、wxwidgetsを学習したときは大量のサンプルコードが付随していましたので、それが学習の助けになりました。

しかし最近、fbxsdkの学習をしてみると、参考にできるサイトも少なく、本に至ってはほぼ存在しません。なので公式のドキュメントを読み進めていってるのですが、全然わかりません。

リファレンスというかドキュメントの見方がよくわからないので、どのように学習していけばよいのか教えてください。

行動規範の内容に同意します

回答2件

ベストアンサー

fbxsdkに限らないドキュメントの読み方について書きます。

まず注意が必要なことは、ライブラリのドキュメントというのは多くの場合、正引きのリファレンスになっているということです。これは「機能があって、それに対して機能の説明がある」というものです。逆引きリファレンス(英語圏ではcookbookと呼ばれる)ですと「やりたいことがあって、その方法の説明がある」というものになりますが、これを公式で作っていることは少ないです(多少のサンプルはあっても、それは始めるために必要な程度)。

その上での読み方ですが、私は以下のようにしています：

まず、Getting StartedやIntroduction、Motivation、Overviewといった項を読み、そのライブラリが何を目的としているのかを理解します。これは、自分が解決したい問題にライブラリ自体が合致するかを確認することも読む目的に含みます
次に、そのライブラリを使ったサンプルコード、チュートリアルを読みます。これによって、ライブラリの簡単な使い方を学びます。ただし、それはエラーハンドリングやコーナーケースを廃したものであることが多いため、この段階のコードをそのまま自分のプロダクトコードに持っていくと痛い目に合う可能性があります
次に、パフォーマンスや設計論拠(Design rationale)の項を確認し、たとえばデフォルトの使い方をしたときにパフォーマンス側に倒しているか安全側に倒しているかや、凝ったことをしたいときのためにカスタマイゼーションポイントがあるかなどを確認します
それから、APIのリファレンスを読みます。リファレンスはまず、あまり整理されていないドキュメントであれば名前から機能を探すことになってしまいますが、なんとかして機能を探し出すことになります
APIのリファレンスでは、以下のようなことを確認します。どのようなときにエラーが起きるか、パラメータの意味と値の範囲、そのパラメータを与えたことによってどのような結果になるのか(戻り値、入出力、オブジェクトの状態)などを確認します
歴史の深いライブラリであれば、ひとつの目的のために複数の解決方法が用意されている場合がありますので、それも探しましょう。それは個々のAPIのドキュメントに「こちらも参照」のように書いてある場合もあれば、書いていないこともあります。HistoryやRelease Noteといったページでバージョン間の更新内容によって「このような問題を解決するためにxx APIを追加」のように書いてあることもあるので、それも確認するとよいでしょう

それでもわからないことは、メーリングリストやStackOverflowなどで検索・質問することになるでしょう(開発者がそこを見ていることが多いからです)。
私が現時点で思いつくドキュメントの読み方はこんなところです。参考になれば幸いです。

投稿2017/03/22 15:24

編集2017/03/23 06:40