<p dir="auto">I believe we need better standards for documenting optional arguments. In the manual I sometimes see it as</p>
<div class="snippet-clipboard-content notranslate position-relative overflow-auto" data-snippet-clipboard-copy-content="foo(arg [,optional_arg])"><pre class="notranslate"><code class="notranslate">foo(arg [,optional_arg])
</code></pre></div>
<p dir="auto">So maybe we need to have that for all optional arguments in the help docs, instead of the often ambiguous</p>
<div class="snippet-clipboard-content notranslate position-relative overflow-auto" data-snippet-clipboard-copy-content="foo(arg, [optional_arg])"><pre class="notranslate"><code class="notranslate">foo(arg, [optional_arg])
</code></pre></div>
<p dir="auto">That latter maybe confused for an array.</p>
<p dir="auto">The Julia manual often uses the syntax <code class="notranslate">foo(a [, b])</code> to denote optional arguments.  Now that Julia has its own optional-argument syntax, wouldn't it be better to use this in the documentation, i.e. write <code class="notranslate">foo(a, b=c; kw=foo)</code>?</p>