What do the brackets around the arguments mean when reading documentation for a method?

Question

Often when reading documentation on what arguments can be passed to a method, I see brackets used within the arguments list like this:

example of brackets used within arguments on method documentation

What do the brackets mean in this context? Why are the commas inside the brackets?

Brackets mean *optional*, just like in every other API/library documentations. — Derek 朕會功夫, Feb 09 '14 at 01:57

score 42 · Accepted Answer · answered Feb 09 '14 at 01:50

42

required [optional] <required> [<optional>, <but both needed>].

This is almost always the case.

answered Feb 09 '14 at 01:50

Zoey Mertes

3,139
19
23

1

TIL! I had always wondered about the `[,]` syntax. – Mendhak Feb 09 '14 at 02:06
4

I am shocked more tutorials don't explain the notation more. Its a mistake to assume people know what [, param] means. Thank you for the good answer. – kiwicomb123 Jul 18 '17 at 04:49

score 7 · Answer 2 · answered Feb 09 '14 at 01:53

The brackets around a parameter means that it is optional.

When written separately like that, it means that you can use any of the parameters in any combination. The method determines what you use from the data type of the values. All these combinations can be used for that method:

.animate(properties, duration, easing, complete)
.animate(properties, duration, easing)
.animate(properties, duration, complete)
.animate(properties, duration)
.animate(properties, easing, complete)
.animate(properties, easing)
.animate(properties, complete)
.animate(properties)

You can see brackets used in other ways than around each parameters. For example:

.method(p1 [, p2 [, p3]])

This means that the second and third parameters are optional, and the third parameter can only be used if the second parameter is there.

You have 4 parameters though? Where is p4? – basickarl Dec 18 '19 at 14:26 — basickarl, Dec 18 '19 at 14:26

score 0 · Answer 3 · answered Feb 09 '14 at 01:48

The square brackets mean they are optional parameters. You need not pass the optional parameters. .animate(properties) will work . Also the commas are inside the bracket because if it were outside, they would trail

animate(properties, [duration]) would mean properties and , are mandatory, whereas duration is not... It would like : animate(properties,)

What do the brackets around the arguments mean when reading documentation for a method?

3 Answers3

Linked

Related