<p dir="auto">I see two different conventions being used for including optional arguments in docstrings, one where the argument alone is wrapped in <code class="notranslate">[arg]</code>, and one where the preceding comma is included <code class="notranslate">[, arg]</code>. 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</p>
<div class="highlight highlight-source-julia notranslate position-relative overflow-auto" dir="auto" data-snippet-clipboard-copy-content="help?&gt; 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)"><pre class="notranslate">help?<span class="pl-k">&gt;</span> round
  <span class="pl-c1">round</span>(z<span class="pl-k">::</span><span class="pl-c1">Complex</span>[, RoundingModeReal, [RoundingModeImaginary]]) <span class="pl-c"><span class="pl-c">#</span> comma included for the first argument but not the second?</span>
  <span class="pl-c1">round</span>(z<span class="pl-k">::</span><span class="pl-c1">Complex</span>[, RoundingModeReal, [RoundingModeImaginary]]; digits<span class="pl-k">=</span>, base<span class="pl-k">=</span><span class="pl-c1">10</span>) <span class="pl-c"><span class="pl-c">#</span> what's up with the value for digits?</span>
  <span class="pl-c1">round</span>(z<span class="pl-k">::</span><span class="pl-c1">Complex</span>[, RoundingModeReal, [RoundingModeImaginary]]; sigdigits<span class="pl-k">=</span>, base<span class="pl-k">=</span><span class="pl-c1">10</span>)

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

  <span class="pl-c1">round</span>([T,] x, [r<span class="pl-k">::</span><span class="pl-c1">RoundingMode</span>])   <span class="pl-c"><span class="pl-c">#</span> comma included for T but not for r</span>
  <span class="pl-c1">round</span>(x, [r<span class="pl-k">::</span><span class="pl-c1">RoundingMode</span>]; digits<span class="pl-k">::</span><span class="pl-c1">Integer</span><span class="pl-k">=</span><span class="pl-c1">0</span>, base <span class="pl-k">=</span> <span class="pl-c1">10</span>) <span class="pl-c"><span class="pl-c">#</span> comma not included for r</span>
  <span class="pl-c1">round</span>(x, [r<span class="pl-k">::</span><span class="pl-c1">RoundingMode</span>]; sigdigits<span class="pl-k">::</span><span class="pl-c1">Integer</span>, base <span class="pl-k">=</span> <span class="pl-c1">10</span>)</pre></div>
<p dir="auto">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.</p>
<p dir="auto">In investigating what appeared to be a code coverage issue with CSV.jl, <a class="user-mention notranslate" data-hovercard-type="user" data-hovercard-url="/users/omus/hovercard" data-octo-click="hovercard-link-click" data-octo-dimensions="link_type:self" href="https://github.com/omus">@omus</a> and I stumbled upon an unusual dispatch issue. It can be summarized like this:</p>
<div class="highlight highlight-source-julia notranslate position-relative overflow-auto" dir="auto" data-snippet-clipboard-copy-content="julia&gt; function foo(x=Type)
           println(&quot;foo&quot;)
       end;

julia&gt; function foo{T}(x::T)
           println(&quot;Method foo{T}&quot;)
       end;

julia&gt; foo()
Method foo{T}"><pre class="notranslate">julia<span class="pl-k">&gt;</span> <span class="pl-k">function</span> <span class="pl-en">foo</span>(x<span class="pl-k">=</span>Type)
           <span class="pl-c1">println</span>(<span class="pl-s"><span class="pl-pds">"</span>foo<span class="pl-pds">"</span></span>)
       <span class="pl-k">end</span>;

julia<span class="pl-k">&gt;</span> <span class="pl-k">function</span> <span class="pl-en">foo</span><span class="pl-c1">{T}</span>(x<span class="pl-k">::</span><span class="pl-c1">T</span>)
           <span class="pl-c1">println</span>(<span class="pl-s"><span class="pl-pds">"</span>Method foo{T}<span class="pl-pds">"</span></span>)
       <span class="pl-k">end</span>;

julia<span class="pl-k">&gt;</span> <span class="pl-c1">foo</span>()
Method foo{T}</pre></div>
<p dir="auto">As <a class="user-mention notranslate" data-hovercard-type="user" data-hovercard-url="/users/omus/hovercard" data-octo-click="hovercard-link-click" data-octo-dimensions="link_type:self" href="https://github.com/omus">@omus</a> has pointed out, the issue is that this:</p>
<div class="highlight highlight-source-julia notranslate position-relative overflow-auto" dir="auto" data-snippet-clipboard-copy-content="function foo(x=Type)
    println(&quot;foo&quot;)
end"><pre class="notranslate"><span class="pl-k">function</span> <span class="pl-en">foo</span>(x<span class="pl-k">=</span>Type)
    <span class="pl-c1">println</span>(<span class="pl-s"><span class="pl-pds">"</span>foo<span class="pl-pds">"</span></span>)
<span class="pl-k">end</span></pre></div>
<p dir="auto">is lowered to:</p>
<div class="highlight highlight-source-julia notranslate position-relative overflow-auto" dir="auto" data-snippet-clipboard-copy-content="function foo()
    foo(Type)
end

function foo(x)
    println(&quot;foo&quot;)
end

function foo{T}(x::T)
    println(&quot;Method foo{T}&quot;)
end"><pre class="notranslate"><span class="pl-k">function</span> <span class="pl-en">foo</span>()
    <span class="pl-c1">foo</span>(Type)
<span class="pl-k">end</span>

<span class="pl-k">function</span> <span class="pl-en">foo</span>(x)
    <span class="pl-c1">println</span>(<span class="pl-s"><span class="pl-pds">"</span>foo<span class="pl-pds">"</span></span>)
<span class="pl-k">end</span>

<span class="pl-k">function</span> <span class="pl-en">foo</span><span class="pl-c1">{T}</span>(x<span class="pl-k">::</span><span class="pl-c1">T</span>)
    <span class="pl-c1">println</span>(<span class="pl-s"><span class="pl-pds">"</span>Method foo{T}<span class="pl-pds">"</span></span>)
<span class="pl-k">end</span></pre></div>
<p dir="auto">and since <code class="notranslate">foo{T}(x::T)</code> is deemed more specific than <code class="notranslate">foo(x)</code>, <code class="notranslate">foo{T}(x::T)</code> is called instead of <code class="notranslate">foo(x)</code>.</p>
<p dir="auto">It seems like a warning might be appropriate in this case.</p>
<p dir="auto">In the above example, I get the same behaviour on both 0.5 and 0.6, using these versions:</p>
<div class="highlight highlight-source-julia notranslate position-relative overflow-auto" dir="auto" data-snippet-clipboard-copy-content="julia&gt; versioninfo()
Julia Version 0.5.1-pre+55
Commit 8d4ef37* (2017-02-13 09:11 UTC)
Platform Info:
  System: Darwin (x86_64-apple-darwin16.4.0)
  CPU: Intel(R) Core(TM) i7-6567U CPU @ 3.30GHz
  WORD_SIZE: 64
  BLAS: libopenblas (USE64BITINT DYNAMIC_ARCH NO_AFFINITY Haswell)
  LAPACK: libopenblas64_
  LIBM: libopenlibm
  LLVM: libLLVM-3.7.1 (ORCJIT, broadwell)"><pre class="notranslate">julia<span class="pl-k">&gt;</span> <span class="pl-c1">versioninfo</span>()
Julia Version <span class="pl-c1">0.5</span>.<span class="pl-c1">1</span><span class="pl-k">-</span>pre<span class="pl-k">+</span><span class="pl-c1">55</span>
Commit <span class="pl-c1">8</span>d4ef37<span class="pl-k">*</span> (<span class="pl-c1">2017</span><span class="pl-k">-</span><span class="pl-c1">02</span><span class="pl-k">-</span><span class="pl-c1">13</span> <span class="pl-c1">09</span><span class="pl-k">:</span><span class="pl-c1">11</span> UTC)
Platform Info<span class="pl-k">:</span>
  System<span class="pl-k">:</span> Darwin (x86_64<span class="pl-k">-</span>apple<span class="pl-k">-</span>darwin16.<span class="pl-c1">4.0</span>)
  CPU<span class="pl-k">:</span> <span class="pl-c1">Intel</span>(R) <span class="pl-c1">Core</span>(TM) i7<span class="pl-k">-</span><span class="pl-c1">6567</span>U CPU @ <span class="pl-c1">3.30</span>GHz
  WORD_SIZE<span class="pl-k">:</span> <span class="pl-c1">64</span>
  BLAS<span class="pl-k">:</span> libopenblas (USE64BITINT DYNAMIC_ARCH NO_AFFINITY Haswell)
  LAPACK<span class="pl-k">:</span> libopenblas64_
  LIBM<span class="pl-k">:</span> libopenlibm
  LLVM<span class="pl-k">:</span> libLLVM<span class="pl-k">-</span><span class="pl-c1">3.7</span>.<span class="pl-c1">1</span> (ORCJIT, broadwell)</pre></div>
<div class="highlight highlight-source-julia notranslate position-relative overflow-auto" dir="auto" data-snippet-clipboard-copy-content="julia&gt; versioninfo()
Julia Version 0.6.0-pre.alpha.5
Commit b1242df* (2017-02-28 18:33 UTC)
Platform Info:
  OS: macOS (x86_64-apple-darwin16.4.0)
  CPU: Intel(R) Core(TM) i7-6567U CPU @ 3.30GHz
  WORD_SIZE: 64
  BLAS: libopenblas (USE64BITINT DYNAMIC_ARCH NO_AFFINITY Haswell)
  LAPACK: libopenblas64_
  LIBM: libopenlibm
  LLVM: libLLVM-3.9.1 (ORCJIT, skylake)"><pre class="notranslate">julia<span class="pl-k">&gt;</span> <span class="pl-c1">versioninfo</span>()
Julia Version <span class="pl-c1">0.6</span>.<span class="pl-c1">0</span><span class="pl-k">-</span>pre<span class="pl-k">.</span>alpha.<span class="pl-c1">5</span>
Commit b1242df<span class="pl-k">*</span> (<span class="pl-c1">2017</span><span class="pl-k">-</span><span class="pl-c1">02</span><span class="pl-k">-</span><span class="pl-c1">28</span> <span class="pl-c1">18</span><span class="pl-k">:</span><span class="pl-c1">33</span> UTC)
Platform Info<span class="pl-k">:</span>
  OS<span class="pl-k">:</span> macOS (x86_64<span class="pl-k">-</span>apple<span class="pl-k">-</span>darwin16.<span class="pl-c1">4.0</span>)
  CPU<span class="pl-k">:</span> <span class="pl-c1">Intel</span>(R) <span class="pl-c1">Core</span>(TM) i7<span class="pl-k">-</span><span class="pl-c1">6567</span>U CPU @ <span class="pl-c1">3.30</span>GHz
  WORD_SIZE<span class="pl-k">:</span> <span class="pl-c1">64</span>
  BLAS<span class="pl-k">:</span> libopenblas (USE64BITINT DYNAMIC_ARCH NO_AFFINITY Haswell)
  LAPACK<span class="pl-k">:</span> libopenblas64_
  LIBM<span class="pl-k">:</span> libopenlibm
  LLVM<span class="pl-k">:</span> libLLVM<span class="pl-k">-</span><span class="pl-c1">3.9</span>.<span class="pl-c1">1</span> (ORCJIT, skylake)</pre></div>
<p dir="auto">However, I get different behaviour depending on whether I call <code class="notranslate">foo()</code> in between the definitions.</p>
<p dir="auto">In 0.5:</p>
<div class="highlight highlight-source-julia notranslate position-relative overflow-auto" dir="auto" data-snippet-clipboard-copy-content="julia&gt; function foo(x=Type)
           println(&quot;foo&quot;)
       end;

julia&gt; foo()
foo

julia&gt; function foo{T}(x::T)
           println(&quot;Method foo{T}&quot;)
       end;

julia&gt; foo()
foo"><pre class="notranslate">julia<span class="pl-k">&gt;</span> <span class="pl-k">function</span> <span class="pl-en">foo</span>(x<span class="pl-k">=</span>Type)
           <span class="pl-c1">println</span>(<span class="pl-s"><span class="pl-pds">"</span>foo<span class="pl-pds">"</span></span>)
       <span class="pl-k">end</span>;

julia<span class="pl-k">&gt;</span> <span class="pl-c1">foo</span>()
foo

julia<span class="pl-k">&gt;</span> <span class="pl-k">function</span> <span class="pl-en">foo</span><span class="pl-c1">{T}</span>(x<span class="pl-k">::</span><span class="pl-c1">T</span>)
           <span class="pl-c1">println</span>(<span class="pl-s"><span class="pl-pds">"</span>Method foo{T}<span class="pl-pds">"</span></span>)
       <span class="pl-k">end</span>;

julia<span class="pl-k">&gt;</span> <span class="pl-c1">foo</span>()
foo</pre></div>
<p dir="auto">In 0.6:</p>
<div class="highlight highlight-source-julia notranslate position-relative overflow-auto" dir="auto" data-snippet-clipboard-copy-content="julia&gt; function foo(x=Type)
           println(&quot;foo&quot;)
       end;

julia&gt; foo()
foo

julia&gt; function foo{T}(x::T)
           println(&quot;Method foo{T}&quot;)
       end;

julia&gt; foo()
Method foo{T}"><pre class="notranslate">julia<span class="pl-k">&gt;</span> <span class="pl-k">function</span> <span class="pl-en">foo</span>(x<span class="pl-k">=</span>Type)
           <span class="pl-c1">println</span>(<span class="pl-s"><span class="pl-pds">"</span>foo<span class="pl-pds">"</span></span>)
       <span class="pl-k">end</span>;

julia<span class="pl-k">&gt;</span> <span class="pl-c1">foo</span>()
foo

julia<span class="pl-k">&gt;</span> <span class="pl-k">function</span> <span class="pl-en">foo</span><span class="pl-c1">{T}</span>(x<span class="pl-k">::</span><span class="pl-c1">T</span>)
           <span class="pl-c1">println</span>(<span class="pl-s"><span class="pl-pds">"</span>Method foo{T}<span class="pl-pds">"</span></span>)
       <span class="pl-k">end</span>;

julia<span class="pl-k">&gt;</span> <span class="pl-c1">foo</span>()
Method foo{T}</pre></div>