Another question:

for slice syntax -> arr.slice([start], [end])
Do square bracket serve any special purpose here?

Another question:

for slice syntax -> arr.slice([start], [end]) Do square bracket serve any special purpose here?

It's an old convention for "optional".

Mmm...
Should be:
arr.slice( [start] [,end] )

Ok, then the splice syntax is correct.But it do look confusing.

Should I

• close this PR
  or
• revert that change and make change to the slice syntax?

Hi all, it should actually be arr.splice(start[, deleteCount, elem1, ..., elemN]), as it is. All parameters optional except of the first one. It's a GNU syntax of method signatures for documentations based on BNF. It's a bit obscure and not very beginner friendly, so I was already thinking whether we should adopt a different style such as the one MDN docs are using. Let's keep this open.

I like the brackets, the single line is more clear when you know the brackets purpose.
I suggested a font change just for the brackets. If you paint them gray and slightly bigger, your brain will recognize they are not part of the syntax.
Maybe the dots should be changed too.

But
Consider adopting MDN style.
MDN has influence in the community, a single convention would be user friendly.

It may be worth creating a separate article on this syntax so that people can be introduced to it, or at least provide a link. Unfortunately there isn't much resources on this online, there seems to be no standard. The only relevant discussion about this I can find is https://stackoverflow.com/questions/10925478/how-to-interpret-function-parameters-in-software-and-language-documentation.

I'd stay with brackets.
Imagine that stackoverflow link example in mdn style.

After "manual and specifications"
Title
"Syntax conventions"
Body
"Square brackets mean optional"
Odd.