Lendo documentação muitas vezes já vi isso mas não entendo porque é assim:
JSON.parse(text[, reviver])
Por que a vírgula não fica para o lado de fora? Por exemplo, assim:
JSON.parse(text,[ reviver])
Tem alguma explicação?
Os colchetes indicam que o parâmetro é opcional. A vírgula fica dentro dos colchetes porque ela própria faz parte de todo o conteúdo que é opcional.
Ou seja, se fosse assim:
JSON.parse(text,[ reviver])
Isso daria a entender que eu poderia chamar a função assim: JSON.parse(text,)
(até pode em JS, mas em outras linguagens com sintaxe mais rígida, daria erro).
Porém, se tivéssemos, por exemplo, uma função com vários parâmetros opcionais e a vírgula fosse documentada fora dos colchetes:
JSON.stringify(value, [replacer], [space])
Aí daria a entender que eu poderia fazer JSON.stringify(value,,)
(e isso nem o JS aceita).
Claro que tem um certo preciosismo e "todo mundo entenderia sem problemas" que não é para deixar essas vírgulas no final. Mas ao colocar a vírgula dentro dos colchetes, estou indicando que todo o bloco "vírgula + parâmetro" é opcional (ou coloca ambos, ou nenhum).
Sei que para alguns parece pedante, mas acho importante ter uma documentação clara, sem ambiguidades e nem margem para intepretações erradas. Sem contar que demonstra mais cuidado com os detalhes. Provavelmente é por isso que muitos colocam a vírgula dentro dos colchetes.
Embora a outra resposta (antes de ser editada e apagada) tenha citado a notação EBNF (que de fato usa colchetes para indicar que algo é opcional), as origens desta notação parecem ser mais antigas.
Primeiro, vale lembrar que não existe um padrão oficial definido para esse tipo de documentação. Não no sentido de ter uma norma ISO, RFC, especificação, ou seja lá o que for.
Não encontrei fontes que cravam com certeza a origem exata, mas a referência mais antiga que encontrei foi o UNIX PROGRAMMER'S MANUAL (escrito em 1971, mais de 20 anos antes do EBNF). Na introdução é dito que:
Square brackets (
[]
) around an argument indicate that the argument is optional
Esta é portanto uma forte candidata à "origem" (pelo menos até alguém encontrar uma referência mais antiga).
Eu acho que faz sentido imaginar que este manual tenha influenciado a notação das documentações modernas. Afinal, o contexto é muito similar (documentação/manual).
E também faz sentido que essa mesma notação tenha sido usado em outros contextos, como o EBNF (que é uma notação para definir gramáticas e descrever linguagens formais, o que não tem a ver com documentação em si). Afinal, muita coisa em computação é assim, a sintaxe e terminologia de alguns contextos acabam sendo aplicados ou adaptados para outros, e o uso de colchetes para indicar algo opcional seria apenas mais um caso.
Mas creio que dá para afirmar com certo grau de certeza que a origem desta notação não é o EBNF.
Ver também: