優れたAPIドキュメントは何だと思いますか？
私はいつもJava APIに関するドキュメントが好きでしたが、一般的に言って、APIが不足していると考える人もいます。それで、APIドキュメントの良い例は何だと思いますか？
回答にはリンクまたは実際の例を含めてください。私（そしてもちろん他の人）が私たち自身の文書を改善するために使用できる参照が欲しいです。
優れたドキュメントには次のものが必要です。
- データ型の仕様-多くの場合、実際の関数よりも重要です。これを軽く扱わないでください。
- 機能仕様（これは明らかです）。与えられた機能が何をするのか、なぜそれをするのか（明白でない場合）、そしてもしあれば警告を含みます。
- 全体を論理エンティティにバインドする導入ドキュメント。実際のAPIコードの範囲を超えて、意図、正しい使用パターン、およびアイデアを説明します。通常、50の異なる関数が与えられ、どれを使用する必要があるのかわかりません必須特定の場合以外は使用しないでください。よりあいまいな代替手段に推奨され、なぜそれらを使用する必要があるのか仕方。
- 例。時にはそれらは他のすべてよりも重要です
GTK +で任意の色の任意の形を描く方法を知っています。描画色の変更に、非常にあいまいで直感的でない3行の非常に長いコード行が必要な理由はまだわかりません。 SVGAlibのsetcolorRGB(r,g,b); draw(x1,y1,x2,y2);を思い出すと、GTK +の作者が何を持っているのかを理解するのが非常に難しいと思います。たぶん、それらを使用する関数を単に文書化するのではなく、基礎となる概念を説明していれば、私は理解するでしょう...
別の例：昨日、SQLiteを理解するための回答を得ました。列からデータを抽出する関数がsigned long longを返すことを理解しました。整数列は1、2、4、6、および8バイトの長さである可能性があることを理解しました。列を「UNSIGNEDINT8」または「TINYINT」として定義できることを理解しました。 「アフィニティ」の意味がよくわかりませんでした。両方に「INTEGER」アフィニティがあることを知っていました。タイムスタンプをUNSIGNEDINTEGERにするかINT8にするか、INT8を8桁にするか8バイトにするか、そしてその難解な6バイトintの名前を探すのに何時間も費やしました。
私が見逃したのは、「UNSIGNED INT8」、「TINYINT」などはすべて「INTEGER」タイプ（常にsigned long long）のシンタックスシュガーシノニムであり、指定された長さは内部ディスクストレージ専用であるということでした。最小ビット数の任意の値に合うように自動的かつ透過的に調整され、API側からは完全に見えずアクセスできません。
実際、iPhone（実際にはMac Cocoa /フレームワーク）のドキュメントはかなり良くなっています。私が好きな機能は次のとおりです。
APIからドキュメントに非常に簡単にジャンプします。
適切にフォーマットされており、コピーして貼り付けたいコードスニペット（メソッドシグネチャなど）が目立ちます。
ドキュメントから直接サンプルコードを含むプロジェクトへのリンク。
自動化されたドキュメント更新メカニズムですが、デフォルトでは、ドキュメントはすべてローカルで開始されます（したがって、不安定なインターネット接続で生活することができます）。
ドキュメントのバリエーションを簡単に切り替えて（OSのさまざまなバージョンを表示するため）、検索を実行するドキュメントのセットを選択することもできます。
概要セクションでは、クラスの目的について説明し、次に目的別にグループ化されたメソッド（作成およびオブジェクト化するメソッド、データを照会するメソッド、型変換を処理するメソッドなど）を分類するセクション、詳細なメソッドの説明が続きます。
また、個人的にはJavadocとJavaシステムドキュメント（長年使用していました）が本当に好きでした。独自のクラス用に独自のカスタムドキュメントを作成する方が少し簡単だったという利点がありました。 XCodeを使用すると、Doxygenを使用して独自のクラスのドキュメントを生成することもできますが、システムフレームワークのドキュメントに多くのドキュメントがあるため、システムクラスのドキュメントと同様にフォーマットするのにさらに手間がかかります。書式設定が適用されました。
優れたAPIには次の特徴があります。
- 習得が容易
- ドキュメントがなくても使いやすい
- 誤用しにくい
- それを使用するコードを読み、維持するのは簡単
- 要件を満たすのに十分強力
- 拡張が簡単
- 聴衆にふさわしい
API設計で私が目にする最も一般的な間違いは、開発者が自動生成されたXMLコメントで十分であると感じ、XMLコメントに基づいてAPIを自動生成する前に行うことです。これが私が話していることです：
///<summary>
/// Performs ObscureFunction to ObscureClass using ObscureArgument
///</summary>
void ObscureClass.ObscureFunction(ObscureArgument) { ... }
上記のようなAPIは逆効果であり、APIを使用する開発者を苛立たせます。優れたAPIドキュメントは、開発者にAPIの使用方法に関するヒントを提供し、他の方法では気付かないAPIの特定の側面についての洞察を提供する必要があります。
私の主な基準は-私が知る必要があるすべてと私が知りたいと思うすべてを教えてください。
QTにはかなりまともなドキュメントがあります： http://doc.qt.digia.com/4.5/index.html
Win32 MSDNも、古くはありませんでしたが、かなり良いです。
Javaドキュメントは私にとって恐ろしいものです。私が知りたくないことはすべて教えてくれますし、知りたいことは何も教えてくれません。NETドキュメントも同様の傾向がありますが、問題はあります。ほとんどの場合、極端な言葉遣い、余分な詳細のオーバーフロー、ひどいページがたくさんあります。同じページにクラスの概要とメソッドの両方が表示されないのはなぜですか。
私は個人的に、優れたドキュメントの完璧な例はPHPのドキュメントであると信じています。
例： http://www.php.net/manual/en/function.fopen.php
効果的なドキュメントには次のものが含まれていると思います。
- パラメータリスト
- （便利な）パラメータの説明
- それらのパラメータが文字列の場合は、考えられるすべてのパラメータをリストアップして説明します
- 成功した実行と失敗した実行の両方の戻り値
- 発生する可能性のある例外/エラー
- 例（最も重要なimo）
オプション：
- 変更ログ
- 他のユーザーからのメモ/例
PHPドキュメントで何かを検索するときはいつでも、「より良い」例を見つけるためにインターネットを精査する必要なしに、それを使用する方法をほぼ正確に知っています。通常、インターネットを検索する必要があるのは唯一の時間です。特定の目的のために一連の関数を使用する方法を見つける必要があるときです。それ以外の場合は、PHPドキュメントが優れたドキュメントの最大の例だと思います。
大丈夫なドキュメントの例はPythonのものだと思います： http://docs.python.org/py3k/library/array.html
それは方法をリストアップしますが、それが何であるか、そしてそれをどのように使用するかを実際に詳細に説明するのはうまくいきません。特にそれをPHP docsと比較すると。
ここにいくつかの本当に悪いドキュメントがあります： Databinder Dispatch 。 Dispatchは、（Java）Apache CommonsHTTPライブラリを抽象化するHTTP用のScalaライブラリです。
それは多くの機能構文の魔法を使用しており、誰もが非常に明確になるわけではありませんが、その明確な説明も、その背後にある設計上の決定も提供していません。 Scaladocsは、従来のJavaスタイルのライブラリではないため、役に立ちません。何が起こっているのかを本当に理解するには、基本的にソースコードを読む必要があり、例を含む多数のブログ投稿を読む必要があります。
ドキュメンテーションは私を愚かで劣った気分にさせることに成功します、そしてそれは確かに私がする必要があることをするのを助けることに成功しません。裏返しは、Rubyコミュニティ（RDocとFAQ /ウェブサイトなどの両方）にあるドキュメントのほとんどです。Javadocだけでなく、より包括的なドキュメントを提供する必要があります。
質問に答えてください：「YでXを行うにはどうすればよいですか？」あなたは答えを知っているかもしれません。私はしません。
私は Twitterのドキュメント が好きです。私にとって、優れたAPIは最新で、読みやすく、例が含まれています。
基本的に、クラスレベルでクラスのストーリーを伝えます。なぜここにあるのですか？それは何をすべきですか？ここには何があるべきですか？誰が書いたの？
メソッドレベルでメソッドのストーリーを伝えます。これは何をしますか？メソッド名がどれほど正確であっても、20〜30文字で説明できるようになるとは限りません。
@著者：
- 誰がこれを書いたのですか？誰がそれを誇りに思っていますか？誰が彼らの仕事を恥じるべきですか？
インターフェースレベルのドキュメントは私に教えてくれます：
- これは何をすべきですか？
- 何が返されますか？
実装レベルのドキュメントは私に教えてくれます：
- それはどのようにそれをしますか？どんなアルゴリズム？どのようなシステム負荷ですか？
- どのような条件が問題を引き起こす可能性がありますか？ null入力は問題を引き起こしますか？負の数は大丈夫ですか？
クラスレベルのドキュメントは私に教えてくれます：
- ここに何が行きますか？どのような方法を見つけることを期待すべきですか？
- このクラスは何を表していますか？
@Deprecatedは私に言います：
- なぜこれが削除される予定なのですか？
- いつ削除される予定ですか？
- 提案された代替品は何ですか？
何かが最終的な場合：
- なぜ私にこれを拡張させたくないのですか？
何かが静的である場合：
- 少なくとも暗黙のうちに、クラスレベルのドキュメントで思い出させてください。
一般的に：宝くじに当たったときに使用する次の開発者のためにこれらを書いています。ヨットをやめて購入することに罪悪感を感じたくないので、明快さに少し注意を払ってください、自分で書いていると思い込まないでください。
副次的な利点として、誰かが2年後に同じコードで作業するように依頼し、それをすべて忘れてしまった場合、優れたコード内ドキュメントから大きなメリットが得られます。
ほんの少しの考え...
例-win32APIドキュメントは、次の理由でiPhoneよりも優れています。
- （短い）コード例
小さくて意味のある例を含むAPIドキュメントに投票します
- （短い）コード例
スクリーンショットやサンプルコードに「Form1」、「asdf」、「testingusers」を表示しないでください
- 優れたAPIは現実世界の問題を解決することであり、いくつかの意味のある例があるはずです
- 優れたAPIは現実世界の問題を解決することであり、いくつかの意味のある例があるはずです
ドキュメントを自動生成しないでください
- コードの記述中に（または同じ人が）ドキュメントを作成しないでください
- docは、プログラマーが通常気にしない見知らぬ人のためのものです。
___V2バージョンのAPIは避けてください
- しかし、それはドキュメントの問題ではありません
優れたAPIドキュメントでは、次のことを明確に説明する必要があると思います。
- このAPIが解決する問題
- いつ使うべきか
- 使うべきではないとき
- APIの「ベストプラクティス」の使用法を示す実際のコード
APIドキュメントではありませんが、Oracleデータベースのドキュメントは非常に便利です。 for SELECTステートメント 。たとえば、使用法を明確にするのに役立つ図を含めるのが好きです。
優れたドキュメントには、少なくとも次のものが必要です。
- 引数にその型以外の追加の制限がある場合は、それらを完全に指定する必要があります。
- メソッドを呼び出す前のオブジェクトの[必須]状態の説明。
- メソッドを呼び出した後のオブジェクトの状態の説明。
- メソッドによって提供されるエラー情報の完全な説明（戻り値、考えられる例外）。単にそれらに名前を付けることは受け入れられない。
- 良い例 ：インデックスが0未満の場合、ArgumentOutOfRangeExceptionをスローします-または-インデックスがCount以上の場合。
- 悪い例：成功した場合は0を返すか、次のE_INVALIDARGのいずれかを返します...（引数を無効にするものを指定せずに）。これは、PS3SDKで採用されている標準の「FU開発者」アプローチです。
さらに、以下が役立ちます。
- メソッドによって例外がスローされた場合のオブジェクトの状態の説明。
- APIのクラスおよびクラスのグループに関するベストプラクティス（たとえば、.NETの 例外 ）。
- 使用例。
これに基づいて：
- greatドキュメントの例はMSDNライブラリです。
- 公平を期すために、これのオンラインバージョンは場合によってはナビゲーションの難しさに苦しんでいます。
- ひどいドキュメントの例はPS3SDKです。 APIを学習するには、特定のメソッドの実際の要件と動作であるかどうかを推測するために、メソッド引数の広範なテストが必要です。
IMO 例は最高のドキュメントです。
優れたAPIドキュメントの最初のポイントは、API自体の適切な命名です。メソッドとパラメーターの名前はすべてを言う必要があります。問題の言語が静的に型指定されている場合は、パラメーターとしてString定数またはint定数の代わりに列挙型を使用して、限られた選択肢のセットから選択します。可能なオプションは、パラメーターのタイプで確認できます。
ドキュメントの「ソフト部分」（コードではなくテキスト）はボーダーケース（パラメーターとしてnullを指定するとどうなるか）をカバーする必要があり、クラスのドキュメントには使用例が含まれている必要があります。
私は本当に好きです Qt4ドキュメンテーション 、それはあなたが物事を機能させるために必要な本質的な情報だけに最初に直面します、そしてあなたがもっと深く掘り下げたいなら、それはサブセクションのすべての厄介な詳細を明らかにします。
私が本当に大好きなのは、ドキュメント全体がQt Creatorに組み込まれているという事実です。これにより、必要なときにいつでも状況依存ヘルプと短い例が提供されます。
私が常にドキュメントで見たかったことの1つは、各関数またはクラスの「合理的な」段落です。なぜこの機能があるのですか？それは何のために作られたのですか？他の方法では達成できないことは何を提供しますか？答えが「何もない」（そして驚くほど頻繁にある）の場合、それは何の省略形であり、なぜそれが独自の機能を持つのに十分重要なのですか？
この段落は簡単に書くことができるはずです-そうでない場合は、おそらく疑わしいインターフェースの兆候です。
私は最近、 this ドキュメント（Lift JSONのライブラリ）に出くわしました。これは、多くの人々が求めているものの良い例のようです：素晴らしい概要、良い例、ユースケース、意図など。
ドキュメントの品質の唯一の基準は、開発をスピードアップすることです。何かがどのように機能するかを知る必要がある場合は、ドキュメントを読んでください。最初のドキュメントのすべてを2番目のドキュメントよりも速く理解した場合、1つのドキュメントは別のドキュメントよりも優れています。
その他の性質は主観的です。スタイル、相互参照、説明…私は本を読むのが好きな人を知っています。本のようなドキュメント（contents/index /etc。を含む）は彼にとって良いでしょう。別の私の友人は、コード内のすべてを文書化するのが好きです。彼が新しいライブラリをダウンロードするとき、彼はソースを取得し、ドキュメントの代わりにそれらを「読み取り」ます。
私は個人的にJavaDocsが好きです。 Apple dev docsのように、低レベルの部分を除いて、たとえば、Obj-Cランタイム（参照部分）はひどく記述されています。いくつかのWebサイトAPIには、私も好きなドキュメントがあります。
MSDNは好きではありません（一般的には良いのですが、同じドキュメントのバリエーションが多すぎるため、迷子になることがよくあります）。
Google API 優れたドキュメントAPIの美しい例です。
彼らは持っている：
- API構造全体の鳥瞰図
- 単一APIの主な機能の概要
- 迅速なフィードバックのための素敵で色付きの例
- 詳細な参考資料
- あなたを最新の状態に保つブログ
- A google groups 問題と解決策を文書化する
- ビデオ
- FAQ
- 記事
- プレゼンテーション
- コードプレイグラウンド
- ドキュメントの山の中を這う検索エンジン
それでおしまい！私がグーグルAPIドキュメントサイトで遊ぶとき、私はくつろいでいます。
ドキュメントは、API設計の全体像の一部にすぎません。そして、後者は単なる命名よりもはるかに重要であると主張することができます。意味のある重複しないメソッド名などを考えてください。
これに関するJoshBlochのプレゼンテーションを見ることを強くお勧めします： http://www.infoq.com/presentations/effective-api-design OR http ：//www.youtube.com/watch？v = aAb7hSCtvGw
これはあなたが探しているものだけでなく、はるかに多くをカバーします。
Doxygenサイトにアクセスして、生成されるHTMLの例を確認してください。それらは良いです：
優れたドキュメントに関するほとんどのことはすでに言及されていますが、APIドキュメントのJavaDocの方法には欠けている側面が1つあると思います。それは、すべての異なるクラスとインターフェイスの使用シナリオを簡単に区別できるようにすることです。ライブラリクライアントで使用する必要があり、使用しないでください。
多くの場合、JavaDocはほとんどすべてのものであり、通常、パッケージのドキュメントページはありません。次に、数百またはそれ以上のクラスのリストに直面します。どこからどのように始めればよいのでしょうか。ライブラリを使用する典型的な方法は何ですか？
JavaDocの一部としてこの情報を簡単に提供する方法についての慣習があればよいでしょう。次に、生成されたAPIドキュメントにより、ライブラリを実装するグループとライブラリを使用するグループの少なくとも2つのグループで、さまざまなグループの人々にさまざまなビューを提供できます。
ほとんどの人が優れたAPIドキュメントを構成するポイントをリストしているので、それらを繰り返すつもりはありません（データ型の仕様、例など）。私はそれがどのように行われるべきかを説明すると思う例を提供するつもりです：
nityアプリケーションブロック （CHMのダウンロードセクションに移動）
このプロジェクトに関係するすべての人々は、それを文書化し、それをどのように使用すべきかについて素晴らしい仕事をしました。 APIリファレンスと詳細なメソッドの説明の他に、全体像、理由、方法を説明する記事やサンプルがたくさんあります。このような優れたドキュメントを備えたプロジェクトはまれであり、少なくとも私が使用して知っているプロジェクトはまれです。
多くの実用的な実例が必須です。 jQueryの APIドキュメント の最近の書き直しは、Djangoの伝説的なドキュメントと同様に良い例です。
私のドキュメントの上部に簡単な概要があり、以下に完全な機能の例があり、これらの下で議論されているのが好きです！特にphpでは、必要な変数タイプとデフォルト値を持つ単純な関数引数が含まれているものがほとんどないことに驚いています。
私は自分のお気に入りのものを見つけるためにトロールしていないので、実際には例をあげることができないのではないかと思いますが、これはおそらく非公式であるためカウントされないことを知っていますが Kohana3.0の非公式WikiBy Kerkness は素晴らしいです！そして Kohana 2.34ドキュメント もかなりうまくレイアウトされています。少なくとも私にとってはそうです。皆さんはどう思いますか？