Julia: Better documentation standards for optional arguments

[mbeltagy]

I believe we need better standards for documenting optional arguments. In the manual I sometimes see it as

foo(arg [,optional_arg])

So maybe we need to have that for all optional arguments in the help docs, instead of the often ambiguous

foo(arg, [optional_arg])

That latter maybe confused for an array.

[nalimilan]

Currently, the only reference is the manual: http://docs.julialang.org/en/latest/manual/documentation/ It advises the f(x[, y]) form, but that's quite recent so the existing docstrings don't really follow this rule.

An issue is that it's quite heavy when there are several optional arguments: f(x[, y[, z]]). Not sure what to do about it.

[tkelman]

I think we should stop using square brackets for this and favor using the actual Julia syntax for optional inputs most places. If there are multiple signatures not implemented via trailing defaults, we can just list the signatures on separate lines.

[nalimilan]

Might work. One would need to go over Base and see how it looks in practice.

[stevengj]

Duplicate of #4902.

[fredrikekre]

Close as dup?