Where can I find some info about a syntax in JS docs?

Question

I have met many times a syntax like arr.fill(value[, start = 0[, end = this.length]]) in JS docs and etc. and I have been forced to understand it myself. I mean spelling of the function's parameters.
It is not a big problem anyway, but I would want to know more about this syntax.

It's kinda pseudo code, arguments in brackets are optional, additionally, values for optional arguments are shown. Usually docs have a "Convention" chapter explaining the syntax. — Teemu, Mar 21 '16 at 15:57
@PaulFitzgerald I have seen it [here](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/fill) — through.a.haze, Mar 21 '16 at 16:03
https://stackoverflow.com/questions/10925478/how-to-read-api-documentation-for-newbs?noredirect=1&lq=1 — Bergi, Feb 20 '18 at 05:48

score 2 · Answer 1 · answered Mar 21 '16 at 15:57

arr.fill(value[, start = 0[, end = this.length]])
         ^---^
    required argument
              ^--------------------------------^
                      optional arguments

This notation specifies the order, requirement, and default values for arguments. No brackets means the argument is required. Brackets means the argument is optional. What's after the equals is the default value for the optional argument.

So given that signature, you have the following options:

arr.fill(value) // start = 0, end = this.length
arr.fill(value, start) // end = this.length
arr.fill(value, start, end)

score 1 · Accepted Answer · edited May 23 '17 at 12:31

This style of documentation is based on the style used in command line tools and man pages, which appears to be based on this standard (following the links from this question). That notation has been pretty standard for API and usage docs for some time.

The brackets ([,start = 0 ...]) denote an optional part of the syntax, although order is important. In your example, the nested brackets show that the preceding sections are required if you want to specify a later parameter.

For the MDN docs, this is combined with a name = value notation to show what parameters are referred to within the function.

Where can I find some info about a syntax in JS docs?

2 Answers2