Syntax for optional arguments in docstrings

[baggepinnen]

I see two different conventions being used for including optional arguments in docstrings, one where the argument alone is wrapped in [arg], and one where the preceding comma is included [, arg]. I happen to find the second one a bit visually confusing, but the first one looks like a vector is created so it's not really optimal either. What are peoples thoughts about this? Should base try to at least be consistent here? Below is an example where the two styles are mixed up, sometimes even on the same line

help?> round
  round(z::Complex[, RoundingModeReal, [RoundingModeImaginary]]) # comma included for the first argument but not the second?
  round(z::Complex[, RoundingModeReal, [RoundingModeImaginary]]; digits=, base=10) # what's up with the value for digits?
  round(z::Complex[, RoundingModeReal, [RoundingModeImaginary]]; sigdigits=, base=10)

  ───────────────────────────────────────────────────────────────────────────────────────────

  round([T,] x, [r::RoundingMode])   # comma included for T but not for r
  round(x, [r::RoundingMode]; digits::Integer=0, base = 10) # comma not included for r
  round(x, [r::RoundingMode]; sigdigits::Integer, base = 10)

I guess it's not the biggest of problems, but the inconsistencies may be a bit confusing, especially to newcomers who need to take in all the other language syntax at the same time.

[fredrikekre]

Duplicate of #4902