How to document a method where the leading arguments are optional?

General Usage
,
1

The julia docstring convention for a function f(x,y) where the second argument is optional, is:

f(x, y=1)

Here 1 is the default value of the argument. This coincides nicely with the method definition. What does one do, however, if x is the optional argument? The choice

f(x=1, y)

seems odd, as we don’t place non-optional arguments after optional ones. The alternative to this is to use square brackets, and express this as

f([x=1], y)

This is what zeros does, for example:

zeros([T=Float64,] dims::Tuple)

However, the docstring convention also states that brackets are to be used in cases where the optional argument does not have a default value, but it does have one in this case. I wonder if the convention is to use brackets in this case anyway?

2

The statement in the docs is:

Optional arguments which do not have a default value should be put in brackets

But I haven’t read anything against using them if there are default values, too. From my point of view, f([x=1], y) looks fine.

3 Likes
3

I presume you mean

f([x=1,] y)

?

4

Yes