use Julia syntax to document optional arguments

[stevengj]

The Julia manual often uses the syntax foo(a [, b]) 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 foo(a, b=c; kw=foo)?

[ViralBShah]

+1

[ivarne]

I would like much more if we used the multiline syntax we have for some functions (like display).

display(x)
display(d::Display, x)
display(mime, x)
display(d::Display, mime, x)

The syntax you propose also have the same problem as the old one. If someone just copies the signature from the manual they will get errors, if the method has default paramters for non-keyword arguments. The signature bin(2,pad=0) can't be called by copying, if the user doesn't understand that he must remove the pad= part.

julia> bin(2,pad=0)
ERROR: function bin does not accept keyword arguments

[stevengj]

It's true that my proposal cannot be copy-and-pasted into the code, but for that matter neither can display(d::Display, x) unless the user has defined variables named d and x.

My feeling is that just as we expect the reader to recognize display(d::Display, x) as a declaration, not a code snippet, Julia users should be able to recognize the foo(x, bar=3; baz=7) declaration syntax. The nice thing about this is:

• It documents the values of the defaults so that they can be seen at a glance.
• It is much more compact than listing each variant separately, especially when there are multiple optional positional arguments, e.g. plan_fft(A, dims=1:ndims(A), flags=FFTW.ESTIMATE, timelimit=<none>)

However, when the optional arguments come first, we probably should still list the variants separately (although I would prefer to do so on a single line, separated by commas, if it is natural to document them together), e.g. listen(addr, port), listen(port) rather than listen([addr, ] port).

[stevengj]

See above commit for a possible implementation.

[JeffBezanson]

I'm all in favor of this; I've never really liked sloppy pseudo-syntax like f(a[, b]). Does ReST support the listen(addr, port), listen(port) syntax? What output does it generate for that?

[StefanKarpinski]

It's also annoying that if you write f(a, [b]) it still displays it as f(a[, b]), which to me looks bad and is confusing.

[ivarne]

@JeffBezanson I could not find any obvious breaking in the documentation with the fun(), fun(par) syntax. It just prints the function signature on one line with a comma.

[nolta]

Seems like a bad idea to expect readers to distinguish

plan_r2r(A, kind, dims=1:ndims(A), flags=FFTW.ESTIMATE, timelimit=<none>)

from

plan_r2r(A, kind; dims=1:ndims(A), flags=FFTW.ESTIMATE, timelimit=<none>)

[StefanKarpinski]

I agree that's a bit subtle. We are, however, expecting them to distinguish it as programmers :-\

[stevengj]

The comma/semicolon distinction is a subtlety in the Julia language itself. Maybe using the same distinction in the manual will help to educate users ab

[nolta]

Authoring code is a very focused activity, so the semicolon is fine. But reading documentation, especially function signatures, is usually done in haste.

[StefanKarpinski]

Fair point, but I have occasionally found the comma/semicolon distinction a bit too subtle in code as well.

[timholy]

How about two semicolons ;;? I know it's dumb, but it might help improve visibility.

(Mike, your last comment is positively quote-worthy in any of a variety of contexts!)