Syntax sections - The MDN project 编辑

The syntax section of an MDN reference page contains a syntax box defining the exact syntax that a feature has (e.g. what parameters can it accept, which ones are optional?) This article explains how to write syntax boxes for reference articles.

API reference syntax

Syntax sections for API reference pages are written manually, and they differ depending on which page type includes them. Yet, all have things in common. In each case the section is titled "Syntax", and included at the top of the reference page, just below the introductory material.

In addition, each syntax section starts with a "code" block showing the feature's exact syntax, styled using the "Syntax Box" block style:

A syntax block example

General style rules

A few rules to follow in terms of markup within the syntax block:

• Do not use <code> within the syntax block (or within any code sample block on MDN, either). Not only is it generally useless, but our markup does not want it, and will not render the way you want it to look if you include it.

• All programmer-specified content in a syntax block should be italicized using <em> (the "Italic" button in the editor toolbar):

  responseStr = element.querySelector(selector);

  Here, responseStr is the return value (a variable named by the developer), element is a placeholder for the variable referencing an Element object, and selector is the placeholder for an input parameter to the method.

  You may find some pages where <var> is used instead of <em>; this is also OK, but we generally prefer <em>.

Constructors and methods

Syntax block

Start with a syntax block, like this (see the IntersectionObserver constructor page):

var observer = new IntersectionObserver(callback, options);

or this (see WindowOrWorkerGlobalScope.fetch):

promiseResponse = fetch(input, init);

Sometimes syntax is written using formal syntax notation, for example see the following on Array.prototype.slice():

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

The square brackets mean that the enclosed parameter is optional. We prefer to not use these as they confuse many of our readers. You could instead just omit the square brackets and explain that these parameters are optional in the Parameters section found below the syntax block.

Multiple lines

Sometimes you'll want to include multiple lines, because the method can be used in different forms. For example, see this example (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);

The slice() syntax example could be rewritten like so, to show all possible variations and make it arguably easier to understand:

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

Another good multiple line example is found on the Date constructor page, which has many quite different possibilities for its parameters:

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

Although as mentioned above, we could omit the square brackets and make optional status of parameters clear in the Parameters section.

Concise syntax blocks

The aim is to make the syntax block as pure and unambiguous as definition of the feature's syntax as possible — don't include any irrelevant syntax. For example, you may see this syntax form used to describe promises in many places on the site:

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

But this version is much more concise, and doesn't include the superfluous Promise.prototype.then() method call:

promiseResponse = caches.match(request, options);

Parameters section

Next, include a "Parameters" subsection, which explains what each parameter should be, in a description list. Parameters that are objects containing multiple members can include a nested description list, which itself includes an explanation of what each member should be. Optional parameters should be marked with an {{optional_inline}} macro call next to their name in the description term.

The name of each parameter in the list should be contained in a <code> block.

Note: If the feature does not take any parameters, you don't need to include a "Parameters" section, but you can if you wish include it with content of "None".

Return value section

Next, include a "Return value" subsection, which explains what the return value of the constructor or method is, even if it is undefined. See the above links for examples.

Exceptions section

Finally, include an "Exceptions" subsection, which explains what exceptions can be thrown if a problem is encountered when invoking the constructor/method. This could be because a parameter name has been misspelled or it has been given a value of the wrong datatype, because there is problem with the environment it is being invoked in (e.g. trying to run a secure context-only feature in a non-secure context), or some other reason.

Determining what exceptions are thrown by a method can require a good perusal of the specification. Looking through the spec's step-by-step explanation of how a feature operates will generally provide a solid list of the exceptions and the situations that cause them to be thrown.

The exception names and explanations should be included in a description list.

Note: If no exceptions can be raised on the feature, you don't need to include an "Exceptions" section, but you can if you wish include it with content of "None".

Properties

Syntax block

Start with a syntax block, like this (see IntersectionObserver.root):

var root = IntersectionObserver.root;

For a non-read-only property, it is a good idea to include two lines, which show getting and setting the property (see AudioParam.value):

gain = gainNode.gain.value;
gainNode.gain.value = 0;

Value section

Below the syntax block you need to include a "Value" subsection, which contains a explanation of the property's value — both its data type and what its purpose is.

Exceptions section

If accessing the property can throw an exception, include an "Exceptions" subsection explaining each exception; this should be set up just like the one described for methods and constructors above.

Event handlers

Event handler properties are still properties, but they have some differences in their syntax sections.

Syntax block

Start with a syntax block, like this (see Window.onvrdisplaypresentchange):

window.onvrdisplaypresentchange = functionRef;

And that's it — event handler properties are always settable, and always contain a function, therefore no more information is needed.

JavaScript reference syntax

JavaScript built-in object reference pages follow the same basic rules as API reference pages, e.g. for methods and properties. There are a few differences that you might observe:

• For built-in objects with a single constructor, the constructor syntax is often included on the object landing page. See Date for example. You'll notice that static methods (those that exist on the Date object itself) are listed under "Methods", whereas instance methods are listed under "Date.prototype methods".
• You'll also notice that methods that have no parameters/exceptions are more likely to have those subsections not included at all on JavaScript reference pages. See Date.getDate() and Date.now() for examples.

CSS reference syntax

Properties

CSS property reference pages include a "Syntax" section, which used to be found at the top of the page but is increasingly commonly found below a section containing a block of code showing typical usage of the feature, plus a live example to illustrate what the feature does (see animation for example).

Note: We do this because CSS formal syntax is complex, not used by many of the MDN readership, and offputting for beginners. Real syntax and examples are more useful to the majority of people.

Inside the syntax section you'll find the following contents.

Optional explanation text

Some CSS properties are self-explanatory and don't really need extra explanation (for example color). Some on the other hand are more complex and need explanation on syntax order, including multiple values, etc. (see animation). In such cases you can include extra explanation before any of the subsections.

Values section

Next, you should include a "Values" section — this contains a description list explaining the CSS value types that make up the value of the property. Each value type should be wrapped in angle brackets and linked to the MDN reference page covering that value type if a page exists for it. For example, see the border property reference — this reference three value types, only one of which is linked (<color>).

Formal syntax

the last section, "Formal syntax", is automatically generated from the data included in the MDN data repo's CSS directory. You just need to include a CSSSyntax macro call below the title, and it will take care of the rest.

The only complication arises from making sure the data you need is present. The properties.json file needs to contain an entry for the property you are documenting, and the types.json file needs to contain an entry for all of the value types used in the property's value.

You need to do this by forking the MDN data repo, cloning your fork locally, making the changes in a new branch, then submitting a pull request against the upstream repo. You can find more details about using Git here.

Selectors

The "Syntax" section of selector reference pages is much simpler than that of property pages. It contains one block styled using the "Syntax Box" style, which shows the basic syntax of the selector, whether it is just a simple keyword (e.g. :hover), or a more complex function value that takes a parameter (e.g. :not()). Sometimes the parameter is explained in a further entry inside the syntax block (see :nth-last-of-type() for an example).

This block is automatically generated from the data included in the MDN data repo's CSS directory. You just need to include a CSSSyntax macro call below the title, and it will take care of the rest.

The only complication arises from making sure the data you need is present. The selectors.json file needs to contain an entry for the selector you are documenting.

You need to do this by forking the MDN data repo, cloning your fork locally, making the changes in a new branch, then submitting a pull request against the upstream repo. You can find more details about using Git here.

HTML reference syntax

HTML reference pages don't have "Syntax" sections — the syntax is always just the element name surrounded by angle brackets, so it isn't needed. the main thing you need to know about HTML elements is what attributes they take and what their values can be, and this is covered in a separate "Attributes" section. See <ol> and <video> for examples.

HTTP reference syntax

HTTP reference syntax is all manually created, and differs depending on what type of HTTP feature you are documenting.

HTTP headers/Content-Security-Policy

HTTP header syntax (and Content-Security-Policy) is documented in two separate sections on the page — "Syntax" and "Directives".

Syntax section

The "Syntax" section shows what a header's syntax will look like, using a syntax block styled using the "Syntax Box" style, including formal syntax to show exactly what directives can be included in the value, in what order, etc. For example, the If-None-Match header's syntax block looks like this:

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

Some headers will have separate request directive, response directive, and extension syntax. If available, these must be included in separate syntax blocks, each under its own subsection. See Cache-Control for an example.

Directive section

The "Directive" section contains a description list containing the names and descriptions of all the directives that can appear inside the syntax.

HTTP request methods

Request method syntax is really simple, just containing a syntax block styled using the "Syntax Box" style that shows how the method syntax is structured. The syntax for the GET method looks like this:

GET /index.html

HTTP response status codes

Again, the syntax for HTTP response status codes is really simple — a syntax block including the code and name. For example:

404 Not Found

SVG reference syntax

SVG elements

SVG element syntax sections are non-existent — just like HTML element syntax sections. Each SVG element reference page just includes a list of the attributes that can apply to that element. See <feTile> for example.

SVG attributes

SVG attribute reference pages also do not include syntax sections.