クライアントサイドの JavaScript API は、Web 上で利用可能な技術の大部分を占めています。MDN には、これらの API で使用できる機能とその使用方法を説明する広範囲な参考資料が含まれています。このガイドセットでは MDN で API リファレンス資料を作成する方法について説明します。

前提条件のリソース

APIの文書化を開始する前に、次のものが必要です。

  1. 最新の仕様:W3C勧告か初期の編集者のドラフトかどうかに関わらず、その API をカバーする仕様の最新ドラフト (またはその仕様を参照) を参照する必要があります。通常それは Web 検索で見つかります。最新のバージョンは「最新ドラフト」、またはそれに類するものの下にリストされている仕様のすべてのバージョンからリンクされることがよくあります。
  2. 最新の最新のWebブラウザ:Firefox Nightly/Chrome Canary のような実験的/アルファ版のものが、あなたが文書化している機能をサポートする可能性が高いはずです。これは初期の/実験的な API を文書化している場合に特に関係します。
  3. デモ/ブログ投稿/その他の情報:できるだけ多くの情報を探しましょう。主なインターフェイス/プロパティ/メソッドが何であるか、主要なユースケースが何であるか、そしてそれを使って簡単な機能を書く方法を学ぶことで、API の仕組みに慣れるための時間を費やすことから始めておくと便利です。
  4. 役に立つエンジニアリング担当者:仕様、API の標準化に携わっている人、またはブラウザでの実装について質問するためのフレンドリーなエンジニアリング担当者を見つけることは本当に便利です。それらを見つけるのに適した場所は次のとおりです。
    • 関連会社に勤めている場合は、社内のアドレス帳。
    • Mozilla の dev-platformdev-webapi のリスト、public-webapps のような W3C のリストなど、その API の議論に関係する公開メーリングリスト。
    • 仕様そのもの。たとえば、Web Audio API の仕様では著者とその連絡先の詳細が上部に表示されます。

高位の構造

What does an API reference need?
この記事では完全な API リファレンスに必要なページについて説明します。
Page types
MDN に繰り返し使用されるいくつかの種類のページがあります。この記事では、これらのページタイプとその目的、および新しいページを作成するときに使用する各テンプレートとテンプレートの例について説明します。

個々のページの機能

これらの記事では、API リファレンスページに必要な個々のページの機能を作成する方法について説明します。

API reference sidebars
MDN API リファレンス記事にサイドバーを含めると、その API に関連する関連インタフェース、チュートリアル、その他のリソースへのリンクが表示されるようにカスタマイズできます。この記事では、この方法について説明します。
Syntax sections
MDN リファレンスページの構文セクションには、フィーチャが持つ正確な構文 (どのパラメータを受け入れるか、どのパラメータをオプションとして使用するかなど) を定義する構文ボックスが含まれています。
Code examples
MDN には、Web プラットフォーム機能の使用方法を示すために、ページ全体に挿入された多数のコード例があります。この記事ではコードの例をページに追加する際に使用できるさまざまなメカニズムと、使用する必要があるものとそのタイミングについて説明します。
Specification tables
MDN のすべてのリファレンスページは、その API またはテクノロジーが定義されている仕様または仕様に関する情報を提供する必要があります。この資料では、これらのテーブルの外観とその構成方法について説明します。
Compatibility tables
MDN には、公開されている Web ドキュメントの互換性テーブルの標準フォーマットがあります。つまり、すべてのブラウザで共有されているDOM、HTML、CSS、JavaScript、SVG などの技術のドキュメントです。この記事では、機能を使用して MDN ページに互換性データを追加する方法について説明します。

ドキュメントのタグと貢献者

このページの貢献者: silverskyvicto
最終更新者: silverskyvicto,