APIドキュメントには、いつ使用するかと使用しない場合のリストを含める必要がありますか？

Question

以下で説明する問題のターゲットユーザーベースは、最も無視され、過小評価されているものの1つです-Programmers/ Developers/Coders。

たとえば、この Java doc を検討してください。これは、本によってAPIに関するさまざまな詳細について説明しています（規則に従って）。

それがすること

それは私に言う

このAPIでできること
APIの目的
このAPIのさまざまなメソッド

しないこと

ただし、ここに記載されていない情報については、他にもたくさんのブログ、記事、および投稿（このQ＆Aサイトには多数あります）があります。

このAPIの長所と短所
いつ使うか
使用しない場合
他のどのAPIでこのAPIが最も推奨されますか
他のどのAPIで、このAPIは最も推奨されないか、使用しないことが推奨されます
aPIをいじる（可能な場合）

問題になるのは

ここから欠落しているこのすべての情報は、このドキュメントになります

読むのは退屈で、リファレンスとしてのみ設計されています。したがって、それを維持および更新するために与えられる/割り当てられる時間はほとんどありません。
他の多くの専門家/経験者に、自分のベストプラクティスリストを作成する機会を提供します。これは、時の試練に耐えられるかどうかにかかわらず、ピアやコミュニティの徹底的なレビューを受けられない可能性があります。
開発者は大量のリンクをブックマークして、場合によっては時期尚早にそれらを信頼する必要があります。

ただし、[〜＃〜] some [〜＃〜]は、APIドキュメントがそのようになっていると想定されており、規則では詳細情報を許可しないと主張する場合がありますそこに表示されます。

だから私のquestionは-APIドキュメントにこれらすべての情報が含まれているのか、それとも単に考えすぎているのか、これらのドキュメントは本来あるべき姿なのか？

icc97 · Accepted Answer

ドキュメントにはあなたが提案する追加情報が含まれている必要があることは間違いなく同意しますが、同時にそれを正しく行うのは難しく、退屈で労力を要します。

John Resig（jQueryの作成者）が jQueryの構築に関するインタビュー 4:19 でインタビューに参加し、彼のドキュメントについて話しますjQueryの例は、彼が行った初期の最良の決定の1つでした。

少し後で（これは彼が言うことの私の言い換えです）：

「優れたプロジェクト、特にオープンソースを管理しようとしている場合、コードは方程式全体のごく一部にすぎません。人々が望むものを作るために多くの時間と労力を費やす必要があります学ぶこと、彼らが学ぶことは簡単であり、一度彼らがそれを学んだら、彼らは後で欲求不満にならずに去ることはありません。」

jQueryのドキュメントは、おそらくあなたが見つける最良の例の1つでしょう。

PHPはプログラミング言語としてよくばかげていますが、ドキュメントは非常に優れています。ユーザーが（投票で）貢献したことも、これに優れた追加機能です。これにより、「使用しない場合」などの追加要件が追加されることがよくあります。

user31143 · Answer

はい、この情報をすべてドキュメントに直接含めると非常に便利です。優れたドキュメントは、API、インターフェース、またはその他のツールを理解するために必要なすべての情報を提供します。これは、それがどのように機能するかという単純な技術的説明を超えるものです。

これを行うドキュメントの例があります。

私がよく知っているのは Perlのドキュメントです。モジュールのドキュメントはjavadocの例に似ていますが、次のような情報が含まれていることがよくあります。

等々。その結果、関数/メソッドを呼び出す方法だけでなく、いつどのようにモジュールを使用するかを開発者に教えます。

または、チェックアウトこのTrello用APIの紹介（タスクを管理するためのオンラインツール）を参照してください。これは、インターフェイスへの参照だけでなく、開始するための重要な情報を提供します。また、オンラインサンドボックスも実際に試してみることができます。

はい、そのjavadocの例よりも優れた方法で実行できます。

ypag · Answer

私はいくつかのAPIを使用し、ドキュメントを読みました。開発者は通常、APIドキュメントを参照して、それを使用する必要があるかどうかを判断しません。このAPIは他のユーザーに対してどこにあるのかなどです。APIドキュメントは、試してみることがわかっている場合にのみ使用されます。このドキュメントは、この特定のAPIとそのクラスとメソッドにできる限り迅速に精通しているはずのドキュメントのように扱われます。通常、コード内で使用する方法を示す「使用」セクションがあります。

APIドキュメントの簡潔さが気に入っています。とはいえ、APIを「試してみる」ことができるインタラクティブなドキュメントを見たいと思います。この部分はAPIを探索するのに役立ち、可能性のあるものだと思います。頭に浮かぶもう1つのことは、APIがクロスプラットフォームになる傾向があるためです。そのため、探索するWebベースのクロスプラットフォームインターフェイスを構築すること自体が作業の一部です。

gurvinder372 · Answer

自分の質問に答えて、他の誰もが完全に対処していないので、いくつかの点に対処します。

はい、APIドキュメントにはこれらの詳細が必要です。これらの詳細は、言語の存続を含む多くのシナリオで絶対的に重要です。また、それらにはいくつかの欠点もあります。

なぜそこにあるべきなのか

より簡単な学習曲線

開発者が最初にGetting StartedチュートリアルまたはHello Worldプログラムを最初に。しかし、この段階はいつかで終わります

要件をさらに掘り下げる必要があるか、
または、同じタスクを実行するために使用できる他のオプションをチェックアウトします。
または、ホイールを再発明するのではなく、タスクを実行するための組み込みAPIを試してみてください。

APIドキュメントにない場合

簡単な学習の欠如これだけでも確実に

新しい/より良いAPIを発見可能にするのは簡単

一部の代替案はAPIドキュメントで利用できる場合があります（代替案としてマークされておらず、APIドキュメントを閲覧した直後に発見されました）。

それらのAPIを自分でテストするか、
またはインターネットでドキュメントまたはチュートリアルを検索し、オンラインで入手できるあらゆる知識を利用します。
または、組織内で進行中の知恵/ベストプラクティスに依存します。

何かがベストプラクティスになると、非常にまれにそれが文書化されている

どのようにベストプラクティスになったか-すべてのテストが実行されたものを意味し、
すべてのシナリオでこのベストプラクティスは有効ですが、
そして最後に、このベストプラクティスが有効でない場合。

現在、APIメーカーが新しいAPIを作成する場合、言語またはAPI自体がAPIドキュメントを通過する文化を宣伝する場合を除いて、開発者は通常、このベストプラクティスのアーティファクト以外を見ることはありません。ライブラリをアップグレードします。

すべきこととすべきでないことのタグ付けが簡単

APIドキュメント自体にAPIを使用することのDo'sおよびDon'tsがある場合、ページにタグを付けるのは簡単です同様に、特定の要件に基づいてAPIを検索およびグループ化することが簡単です。

たとえば、

XA環境でのトランザクション管理のためのXYZ API

または

コンテナーベースの接続プールで作業するときに回避するAPI

必要なAPIと回避すべきAPIのリストを取得する必要があります。これは、APIユーザー（開発者）を助けるだけでなく、APIユーザーのコミュニティによっても大きく助けられ、より速い採用につながります。

欠点のみ？

ドキュメントにそのような労力を注ぐことの唯一の欠点は、APIメーカーがバージョンをリリースする前に多くの影響分析を行う必要があるためです多くにつながるリリースサイクルが遅くなり、APIユーザーのコミュニティへの応答が少なくなります。