0

Why in various programming documentation for functions do they have square brackets around parameters, but they are ordered such that the later parameters seem to be subsets of the first? Or if the brackets in that language delineate arrays it's as if the second parameter is supposed to be inside of the array of the first, but often the parameters are not even supposed to be arrays, and also they have commas in weird places.

I've seen this style all over the place and tried to find some place where it is written down why they do this. Maybe someone just arbitrarily decided on that and other programmers thought, "oh that looks cool, I'll try that in writing my own documentation.." Or maybe there is some big book of rules for how to make programming docs? If so I'd like to know about it. Here is an example: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/slice if you go to the link in the blue box near the top of the page right bellow the h2? heading "syntax" it says this: arr.slice([begin[, end]]) meaning that the first parameter is begin, and the next parameter is end, for the slice method. When you first see something like this it looks like the brackets and commas are randomly placed.. but they do it all over the place and the same way. There must be some method to the madness!

Brew Dain
  • 131
  • 1
  • 3

1 Answers1

0

Brackets around a parameter name indicate that it is an optional parameter. E.g. you can call the slice method without an end parameter. This is just a general rule of language syntax documentation, square brackets indicate optional words/tokens.

Nick Smith
  • 126
  • 2
  • 6
  • Ok but then why wouldn't it be `arr.slice([begin], [end])`? Why the layering as if one is inside the other? – Brew Dain Aug 14 '15 at 21:16
  • 1
    The outer brackets are indicating that slice can have zero arguments, i.e. the entire argument section is optional. The fact that there are no brackets around "begin" indicates that if any arguments are provided, the first argument is begin. The inner brackets around ", end" are to indicate that if begin is provided, then you can also optionally provide end. The way you wrote it would mean you could provide end without begin, but this is invalid according to the specification. – Nick Smith Aug 14 '15 at 21:26
  • 1
    More specifically, I think the reason is that the *comma* is also optional, and should be present exactly when "end" is present. This makes more sense if you consider that when this stuff became widespread, it was also used for e.g. command line utilities not associated with any particular programming language. – Chris Beck Aug 14 '15 at 21:49