MDN リファレンスページの構文の節には、機能が持つ正確な構文を定義する構文ボックスがあります (例えば、どのような引数が受け入れられるか、どれがオプションかなど)。この記事では、リファレンス記事の構文ボックスの書き方を説明します。
API リファレンスページの構文の節は手作業で書かれ、設置するページの種類によって異なります。しかし、共通事項もあります。いずれも節には「構文」という題名を付け、リファレンスページの最上部、導入部分のすぐ下に設置します。
加えて、それぞれの構文の節はその機能の正確な構文を紹介する「構文」ブロックを、 "Syntax Box" ブロックスタイルを使用してスタイル付けしたもので始める必要があります。
A syntax block example
構文ブロック内をマークアップするために従うべき規則がいくつかあります。
構文ブロック内でプログラマーに依存する部分は、 {{HTMLElement("em")}} を使用してイタリック体にしてください (エディターのツールバーの「斜体」ボタン)。
responseStr = element.querySelector(selector);
ここで、 responseStr は返値 (開発者が付ける変数名) であり、 element は {{DOMxRef("Element")}} オブジェクトを参照する変数のプレイスホルダーであり、 selector はメソッドの入力引数のプレイスホルダーです。
ページによっては <var> が <em> の代わりに使用されているのを見かけるかもしれません。これでも良いのですが、一般に <em> を推奨します。
構文ブロックは、次のように始めてください ({{DOMxRef("IntersectionObserver.IntersectionObserver", "IntersectionObserver constructor")}} ページを参照)。
var observer = new IntersectionObserver(callback, options);
または、次のようにします ({{DOMxRef("WindowOrWorkerGlobalScope.fetch")}} を参照)。
promiseResponse = fetch(input, init);
構文は形式文法の表記を使用して書かれることもあります。例えば以下の {{jsxref("Array.prototype.slice()")}} を参照してください。
arr.slice([begin[, end]])
角括弧は内部の引数が省略可能であることを表します。これは読者の多くを混乱させるため、推奨しません。代わりに角括弧を外して、構文ブロックの下にある引数の節で、これらの引数が省略可能であることを説明したほうがいいでしょう。
メソッドが複数の形式で使用されることがあるため、複数の行で記述したい場合があるでしょう。例えば、この ({{DOMxRef("CanvasRenderingContext2D.drawImage")}}) の例をご覧ください。
void ctx.drawImage(image, dx, dy); void ctx.drawImage(image, dx, dy, dWidth, dHeight); void ctx.drawImage(image, sx, sy, sWidth, sHeight, dx, dy, dWidth, dHeight);
slice() の構文の例も、すべての変化形を表示し理解しやすくするために、次のように書き直すことができます。
arr.slice() arr.slice(begin) arr.slice(begin, end)
他の複数行の例として、 {{jsxref("Date")}} コンストラクターのページでは、取りうる引数の組み合わせが全く異なる形でたくさんあることを示しています。
new Date(); new Date(value); new Date(dateString); new Date(year, monthIndex [, day [, hours [, minutes [, seconds [, milliseconds]]]]]);
ただし前述の通り、角括弧を外し、引数の節で引数が省略可能であることを明確にするべきでしょう。
構文ブロックを簡潔にし、その機能の構文の定義の曖昧さをなくすために — 無関係な構文を含めないでください。例えば、このサイトの多くの場所で、 Promise を説明するために次のような形をよく見かけます。
caches.match(request, options).then(function(response) {
// Do something with the response
});
しかし、次のものははるかに簡潔で、余計な {{JSxRef("Promise.prototype.then()")}} メソッド呼び出しを含んでいません。
promiseResponse = caches.match(request, options);
次に、「引数」の項を設置して、それぞれの引数が何であるべきかを説明リストの形で説明してください。複数のメンバーを含むことができるオブジェクトの引数は、入れ子の説明リストで記述し、その中にそれぞれのメンバーが何であるべきかを記述してください。省略可能な引数は、説明する用語の名前の隣に \{{optional_inline}} マクロでマークしてください。
リスト内の各引数の名前は {{HTMLElement("code")}} ブロックの中に含めてください。
メモ: その機能が何も引数を取らない場合は、「引数」の項を設置する必要はありませんが、中身を「なし」として設置しても構いません。
その次に、「返値」の項を設置して、コンストラクターやメソッドの返値が何であるかを説明してください。 undefined の場合にも記述します。例については前述のリンクを参照して下さい。
最後に、「例外」の項を設置して、コンストラクターやメソッドの呼び出し時に問題が発生した場合にどの例外が発生するかを説明してください。発生する原因としては、引数名の綴りが間違っていたり、間違ったデータ型の値が与えられたり、呼び出された環境に問題があったり (例えば、安全なコンテキストで実行する機能を安全でないコンテキストで実行しようとした場合など)、その他の理由であったりする場合などです。
メソッドで発生する例外を特定するには、仕様を十分に精査する必要があります。機能がどのように動作するかについて、仕様書の1つ1つの説明を調べると、一般に例外とそれが発生する状況の確実な一覧を得ることができます。
例外の名前と説明を説明リストに記述してください。
メモ: その機能で発生する例外がない場合は「例外」の項を設置する必要はありませんが、中身を「なし」として設置しても構いません。
次のように構文ブロックで始めてください ({{DOMxRef("IntersectionObserver.root")}} を参照)。
var root = IntersectionObserver.root;
読み取り専用のプロパティではない場合は、二行を使ってプロパティの取得と設定の両方を示すのもいいでしょう ({{DOMxRef("AudioParam.value")}} を参照)。
gain = gainNode.gain.value; gainNode.gain.value = 0;
構文ブロックの下に「値」の項を設置する必要があり、そこでプロパティの値を — データ型とその用途について — 説明してください。
プロパティにアクセスする際に例外が発生する可能性がある場合、「例外」の項を設置してそれぞれの例外を説明してください。これは前述のメソッドやコンストラクターの説明と同様のことをしてください。
イベントハンドラープロパティは確かにプロパティですが、構文の節の中ではいくらかの違いがあります。
次のように構文ブロックで始めてください ({{DOMxRef("Window.onvrdisplaypresentchange")}} を参照)。
window.onvrdisplaypresentchange = functionRef;
以上で十分です。 — イベントハンドラープロパティは常に設定可能で、常に関数が設定されるため、これ以上の情報は不要です。
JavaScript 組込みオブジェクトのリファレンスページは、 API リファレンスページと同様の基本規則に従います。例えばメソッドやプロパティについてです。多少の違いが見られることがあります。
Date オブジェクト自身が持つ) 静的メソッドは、「メソッド」の下の「Date.prototype メソッド」で記述されていることが分かるでしょう。CSS プロパティページには「構文」の節があり、ふつうはページの先頭にありますが、次第に、機能の典型的な使用方法を示すブロックを含む節や、その機能が何を行うかを説明するライブデモ (例えば {{CSSxRef("animation")}} を参照) の下に見られるようになっています。
メモ: このようにしているのは、 CSS の形式文法が複雑であり、 MDN の読者の多くが必要としておらず、初心者にとってとっつきにくいからです。実際の構文と例が多くの人にとってより有用です。
構文の節の中には、次のような内容が見られるでしょう。
CSS プロパティによってはそれ自体が説明的であり、それ以上の説明が本当に必要ない場合があります (例えば {{CSSxRef("color")}})。一方、より複雑で、複数の値などを含む構文の順序の説明が必要なものもあります ({{CSSxRef("animation")}} を参照)。そのような場合、項が始まる前に追加の説明を加えることができます。
次に、「値」の項を入れてください。 — これには説明リストが入り、プロパティの値を構成する値の型を説明します。値の型はそれぞれ山括弧で囲み、その値の型を説明する MDN のリファレンスページがあれば、そこへリンクしてください。例えば、 {{CSSxRef("border")}} プロパティのリファレンスを参照してください。 — これは3つの値の型を参照しており、そのうちの一つ ({{CSSxRef("<color>")}}) だけがリンクになっています。
最後の項、「形式文法」は MDN data リポジトリの CSS ディレクトリにあるデータから自動的に生成されます。タイトルの下で {{TemplateLink("CSSSyntax")}} マクロ呼び出しを記述するだけで、残りのことはマクロがやってくれます。
唯一の問題は、必要なデータが存在することを確認することです。 properties.json ファイルに、文書化しているプロパティの項目が含まれている必要があり、 types.json ファイルには、プロパティの値で使用されるすべての値の型の項目が含まれている必要があります。
これを行うには、 MDN data リポジトリをフォークし、フォークをローカルにクローンし、新しいブランチに変更を行い、上流のリポジトリに向けてプルリクエストを送信してください。 Git の使用についての詳細はこちらにあります。
セレクターのリファレンスページの「構文」の節は、プロパティページよりもずっと簡潔です。ここには "Syntax Box" を使用してスタイル付けされたブロックが1つ入り、ここでセレクターの基本的な構文を、単純なキーワードだけ (例えば {{CSSxRef(":hover")}}) または引数を取るより複雑な関数値 (例えば {{CSSxRef(":not", ":not()")}}) のどちらかで示します。引数を構文ブロックの中の別な項目で説明している場合もあります (例えば {{CSSxRef(":nth-last-of-type", ":nth-last-of-type()")}} を参照してください)。
このブロックは、 MDN data リポジトリの CSS ディレクトリにあるデータから自動的に生成されます。題名の下で {{TemplateLink("CSSSyntax")}} マクロ呼び出しを追加するだけで、残りのことはマクロがやってくれます。
唯一の問題は、必要なデータが存在することを確認することです。 selectors.json ファイルに、文書化しているセレクターの項目が含まれている必要があります。
これを行うには、 MDN data リポジトリをフォークし、フォークをローカルにクローンし、新しいブランチに変更を行い、上流のリポジトリに向けてプルリクエストを送信してください。 Git の使用についての詳細はこちらにあります。
HTML リファレンスページには「構文」の節がありません。 — 構文は常に要素名を山括弧で囲んだものであるため、必要ないからです。 HTML 要素について主に知っておかなければならないことは、どのような属性を取りうるか、その値は何になるかであり、これは別の「属性」の節で扱います。例としては、 {{htmlelement("ol")}} や {{htmlelement("video")}} をご覧ください。
HTTP リファレンスの構文はすべて手作業で作成され、文書化する HTTP の機能によって異なります。
HTTP ヘッダーの構文 (および Content-Security-Policy) ページ上で二つの節に分けて記述します。 — 「構文」と「ディレクティブ」です。
「構文」の節は、ヘッダーの構文がどのようなものかを、 "Syntax Box" スタイルを使用してスタイル付けされた構文ブロックを用いて、値にどのディレクティブが含まれるか、どのような順番かなどの形式文法を含めて示します。例えば、 {{HTTPHeader("If-None-Match")}} ヘッダーの構文ブロックは次のようになります。
If-None-Match: <etag_value> If-None-Match: <etag_value>, <etag_value>, … If-None-Match: *
ヘッダーによっては個別にリクエストディレクティブ、レスポンスディレクティブ、拡張構文があることがあります。存在する場合、それぞれの項の下にある個別の構文ブロックの中に設置する必要があります。例としては {{HTTPHeader("Cache-Control")}} をご覧ください。
「ディレクティブ」の節には、構文に現れる可能性があるすべてのディレクティブの名前と解説を記述した説明リストを設定します。
リクエストメソッドの構文は実に単純で、構文ブロックを設置し、 "Syntax Box" スタイルを用いてスタイル付けし、どのようにメソッドの構文を構成するかを示すだけです。 GET メソッドの構文は次のようになります。
GET /index.html
HTTP レスポンスステータスコードの構文も、実に単純です。 — コードと名前を含む構文ブロックです。例えば次のようになります。
404 Not Found
SVG 要素に構文の節は存在しません。 — HTML 要素の構文の節と同様です。それぞれの SVG 要素のリファレンスページは、その要素に適用することができる属性の一覧を含みます。例えば {{SVGElement("feTile")}} を参照してください。
SVG 属性のリファレンスページにも、構文の節はありません。