構文の節

API リファレンスの構文

API リファレンスページの構文の節は手作業で書かれており、文書化される機能によって若干異なる場合があります。 この節は、「構文」という見出し（通常はレベル 2 の見出し ##）で始まり、リファレンスページの一番上（導入部分のすぐ下）に記述する必要があります。 見出しの下にはその機能の正確な構文を示すコードブロックがあり、コードフェンス ```[markup-language] クラスを使って区分けされています。

以下の例では典型的な構文セクション（JavaScript 関数）の Markdown コードを示しています。

## 構文

```js-nolint
slice()
slice(start)
slice(start, end)
```

全般的なスタイルルール

構文ブロック内をマークアップするために従うべきルールがいくつかあります。

• 行をセミコロン ; で終わらせないでください。 構文の節は、実行可能なコードを表示するためのものではありません。だから、セミコロンを表示するのは意味がありません。

• 構文ブロック内で（または MDN のコードサンプルブロック内でも） <code> を使用しないでください。一般的に役に立たないだけでなく、マークアップはこれを必要としないので、これを含むと見た目の通りにレンダリングされません。

• 関数と引数のみを指定してください。以下、「修正」した例を示します。

  js

  querySelector(selector)
  // responseStr = element.querySelector(selector)
  
  new IntersectionObserver(callback, options)
  // const observer = new IntersectionObserver(callback, options)
  

コンストラクターやメソッドの場合

構文ブロック

構文ブロックは、次のように始めてください（IntersectionObserver() ページを参照）。

new IntersectionObserver(callback, options)

または、次のようにします（Document.hasStorageAccess() を参照）。

hasStorageAccess()

例えば URL.createObjectURL() のようにメソッドが静的な場合は、そのインターフェイスも提供します。

URL.createObjectURL(object)

複数行/オプション引数

多くの異なる方法で使用することができるメソッドは、複数の行に展開し、利用可能な変化形をすべて表示する必要があります。

各オプションはそれ自身の行に記述し、各オプションのコメントと代入は省略する必要があります。例えば、 Array.prototype.slice() は 2 つのオプションの引数を持っており、以下のように文書化されます。

slice()
slice(begin)
slice(begin, end)

同様に、 CanvasRenderingContext2D.drawImage の場合です。

drawImage(image, dx, dy)
drawImage(image, dx, dy, dWidth, dHeight)
drawImage(image, sx, sy, sWidth, sHeight, dx, dy, dWidth, dHeight)

同様に、 Date コンストラクターの場合です。

new Date()
new Date(value)
new Date(dateString)
new Date(year, monthIndex)
new Date(year, monthIndex, day)
new Date(year, monthIndex, day, hours)
new Date(year, monthIndex, day, hours, minutes)
new Date(year, monthIndex, day, hours, minutes, seconds, milliseconds)

形式文法

形式文法記法（BNF を使用したもの）は構文の節で使用すべきではありません。代わりに前述のような複数行の書式に展開したものを使用してください。

形式的な記法により、複雑な構文を簡潔に記述することができますが、多くの開発者には馴染みがなく、特定のプログラミング言語で有効な構文と_矛盾する可能性があります。例えば、 [ ] は「オプション引数」と JavaScript の配列 (Array) の両方の意味があります。これは以下の Array.prototype.slice() の形式文法で見ることができます。

arr.slice([begin[, end]])

有益と思われる特定のケースについては、別な形式文法の節で正式な表記を用いて宣言することができます。

構文ブロックは簡潔に

構文ブロックを簡潔にし、その機能の構文の定義の曖昧さをなくすために。無関係な構文を含めないでください。例えば、このサイトの多くの場所で、プロミスを説明するために次のような形をよく見かけます。

caches.match(request, options).then(function (response) {
  // Do something with the response
})

しかし、次のものははるかに簡潔で、余計な Promise.prototype.then() メソッド呼び出しを含んでいません。

match(request, options)

コールバックの構文ブロック

コールバック関数を受け入れるメソッドでは、コールバックをアロー関数や function 式ではなく、引数として表示させます。

filter(callbackFn)
filter(callbackFn, thisArg)

次に、「引数」の節に、コールバック関数の引数と、その関数が返すと予想されるものを列挙します。

- `callbackFn`
  - : 配列のそれぞれの要素に対して実行する関数です。この関数は、結果の配列に要素を残す場合は[真値](/ja/docs/Glossary/Truthy)を返し、そうでない場合は[偽値](/ja/docs/Glossary/Falsy)を返します。この関数は以下の引数で呼び出されます。
    - `element`
      - : 配列内で現在処理中の要素です。
    - `index`
      - : 配列の、現在処理中の要素のインデックスです。
    - `array`
      - : `filter()` が呼び出された配列です。

任意の数の引数を取る構文

任意の数の引数を受け取るメソッドの場合、構文の節は次のように記述してください。

unshift()
unshift(element1)
unshift(element1, element2)
unshift(element1, element2, /* …, */ elementN)

1 からの番号付けを始めるには、「unshift は配列の先頭に N 個の要素を追加します」というような記述や、「（0 番目の要素ではなく）最初の要素」というような記述が推奨されます。

なお、引数をゼロで渡す場合は、あまり意味がない場合でも常に記載します。次に、「引数」の節にこのように書きます。

- `element1`, …, `elementN`
  - : 配列の先頭に追加する要素です。

{{optional_inline}} を追加してください。

残りの引数の前にいくつかの位置指定のある別の例です。

splice(start)
splice(start, deleteCount)
splice(start, deleteCount, item1)
splice(start, deleteCount, item1, item2)
splice(start, deleteCount, item1, item2, /* …, */ itemN)

引数の項

次に、「引数」の項を設置して、それぞれの引数が何であるべきかを説明リストの形で説明してください。複数のメンバーを含むことができるオブジェクトの引数は、入れ子の説明リストで記述し、その中にそれぞれのメンバーが何であるべきかを記述してください。省略可能な引数は、説明する用語の名前の隣に {{optional_inline}} マクロでマークしてください。

リスト内の各引数の名前は、マークダウンコードのフェンス記法 ` ` に格納する必要があります。

返値の項

その次に、「返値」の項を設置して、コンストラクターやメソッドの返値が何であるかを説明してください。例については前述のリンクを参照して下さい。

返値がない場合は、下記のテキストを使用してください。

なし ({{jsxref("undefined")}})。

例外の項

最後に、「例外」の項を設置して、コンストラクターやメソッドの呼び出し時に問題が発生した場合にどの例外が発生するかを説明してください。発生する原因としては、引数名の綴りが間違っていたり、間違ったデータ型の値が与えられたり、呼び出された環境に問題があったり (例えば、保護されたコンテキストで実行する機能を保護されていないコンテキストで実行しようとした場合など)、その他の理由であったりする場合などです。

メソッドで発生する例外を特定するには、仕様を十分に精査する必要があります。機能がどのように動作するかについて、仕様書の一つ一つの説明を調べると、一般に例外とそれが発生する状況の確実な一覧を得ることができます。

例外の名前と説明を説明リストに記述してください。

プロパティの場合

値の項

構文ブロックの下に「値」の項を設置する必要があり、そこでプロパティの値を — データ型とその用途について — 説明してください。

例外の項

プロパティにアクセスする際に例外が発生する可能性がある場合、「例外」の項を設置してそれぞれの例外を説明してください。これは前述のメソッドやコンストラクターの説明と同様のことをしてください。

JavaScript リファレンスの構文

JavaScript の組み込みオブジェクトのリファレンスページは、 API リファレンスページと同様の基本ルールに従います。例えばメソッドやプロパティについてです。多少の違いが見られることがあります。

• 組込みオブジェクトで単一のコンストラクターを持つものは、コンストラクターの構文がオブジェクトのランディングページに含まれていることが良くあります。例えば Date を参照してください。（Date オブジェクト自身が持つ）静的メソッドは、「メソッド」の下の「Date.prototype メソッド」で記述されていることが分かるでしょう。
• また、引数も例外もないメソッドは、 JavaScript リファレンスページにこれらの節が全く含まれていないことに気が付くでしょう。例えば Date.getDate() や Date.now() を参照してください。

CSS リファレンスの構文

プロパティ

CSS プロパティページには「構文」の節があり、ふつうはページの先頭にありますが、次第に、機能の典型的な使用方法を示すブロックを含む節や、その機能が何を行うかを説明するライブデモ（例えば animation を参照）の下に見られるようになっています。

構文の節の中には、次のような内容が見られるでしょう。

任意の説明文

CSS プロパティによってはそれ自体が説明的であり、それ以上の説明が本当に必要ない場合があります (例えば color)。一方、より複雑で、複数の値などを含む構文の順序の説明が必要なものもあります (animation を参照)。そのような場合、項が始まる前に追加の説明を加えることができます。

値の項

次に、「値」の項を入れてください。 — これには説明リストが入り、プロパティの値を構成する値の型を説明します。値の型はそれぞれ山括弧で囲み、その値の型を説明する MDN のリファレンスページがあれば、そこへリンクしてください。例えば、 border プロパティのリファレンスを参照してください。 — これは3つの値の型を参照しており、そのうちの一つ (<color>) だけがリンクになっています。

形式文法

最後の節「形式文法」は、 {{CSSSyntax}} マクロを使用して自動的に生成されます。このマクロは、@webref/css npm パッケージを使用して CSS 仕様書からデータを取得します。文書内の形式文法を記載するには、次のようにします。

1. ## 形式文法 のように見出しを追加します。
2. この見出しのちょおっかに {{CSSSyntax}} マクロを追加します。

セレクター

セレクターのリファレンスページの「構文」の節は、プロパティページよりもずっと簡潔です。ここには "Syntax Box" を使用してスタイル付けされたブロックが 1 つ入り、ここでセレクターの基本的な構文を、単純なキーワードだけ (例えば :hover) または引数を取るより複雑な関数値（例えば :not()）のどちらかで示します。引数を構文ブロックの中の別な項目で説明している場合もあります（例えば :nth-last-of-type() を参照してください）。

このブロックは、 MDN data リポジトリーの CSS ディレクトリーにあるデータから自動的に生成されます。題名の下で CSSSyntax マクロ呼び出しを追加するだけで、残りのことはマクロがやってくれます。

唯一の問題は、必要なデータが存在することを確認することです。 selectors.json ファイルに、文書化しているセレクターの項目が含まれている必要があります。

これを行うには、 MDN data リポジトリーをフォークし、フォークをローカルにクローンし、新しいブランチに変更を行い、上流のリポジトリーに向けてプルリクエストを送信してください。 Git の使用についての詳細はこちらにあります。

HTML リファレンスの構文

HTML リファレンスページには「構文」の節がありません。 — 構文は常に要素名を山括弧で囲んだものであるため、必要ないからです。 HTML 要素について主に知っておかなければならないことは、どのような属性を取りうるか、その値は何になるかであり、これは別の「属性」の節で扱います。例としては、 <ol> や <video> をご覧ください。

HTTP リファレンスの構文

HTTP リファレンスの構文はすべて手作業で作成され、文書化する HTTP の機能によって異なります。

HTTP ヘッダー/Content-Security-Policy

HTTP ヘッダーの構文（および Content-Security-Policy）ページ上で 2 つの節に分けて記述します。 — 「構文」と「ディレクティブ」です。

構文の節

「構文」の節は、ヘッダーの構文がどのようなものかを、 "Syntax Box" スタイルを使用してスタイル付けされた構文ブロックを用いて、値にどのディレクティブが含まれるか、どのような順番かなどの形式文法を含めて示します。例えば、 If-None-Match ヘッダーの構文ブロックは次のようになります。

If-None-Match: <etag_value>
If-None-Match: <etag_value>, <etag_value>, …
If-None-Match: *

ヘッダーによっては個別にリクエストディレクティブ、レスポンスディレクティブ、拡張構文があることがあります。存在する場合、それぞれの項の下にある個別の構文ブロックの中に設置する必要があります。例としては Cache-Control をご覧ください。

ディレクティブの節

「ディレクティブ」の節には、構文に現れる可能性があるすべてのディレクティブの名前と解説を記述した説明リストを設定します。

HTTP リクエストメソッド

リクエストメソッドの構文は実に単純で、構文ブロックを設置し、 "Syntax Box" スタイルを用いてスタイル付けし、どのようにメソッドの構文を構成するかを示すだけです。 GET メソッドの構文は次のようになります。

GET /index.html

HTTP レスポンスステータスコード

HTTP レスポンスステータスコードの構文も、実に単純です。 — コードと名前を含む構文ブロックです。例えば次のようになります。

404 Not Found

SVG リファレンスの構文

SVG 要素

SVG 要素に構文の節は存在しません。 — HTML 要素の構文の節と同様です。それぞれの SVG 要素のリファレンスページは、その要素に適用することができる属性の一覧を含みます。例えば <feTile> を参照してください。

SVG 属性

SVG 属性のリファレンスページにも、構文の節はありません。

関連情報

• MDN での Markdown