A thing that is perhaps worth noting is that traditionally function signatures in julia doc strings are not actually valid julia-code,
but rather follow something like the conventions used by linux man pages.
https://pubs.opengroup.org/onlinepubs/009695399/basedefs/xbd_chap12.html
In particular
- Arguments or option-arguments enclosed in the ‘[’ and ‘]’ notation are optional and can be omitted. Conforming applications shall not include the ‘[’ and ‘]’ symbols in data submitted to the utility.
- Arguments separated by the ‘|’ vertical bar notation are mutually-exclusive. Conforming applications shall not include the ‘|’ symbol in data submitted to the utility. Alternatively, mutually-exclusive options and operands may be listed with multiple synopsis lines.
- Ellipses ( “…” ) are used to denote that one or more occurrences of an option or operand are allowed. When an option or an operand followed by ellipses is enclosed in brackets, zero or more options or operands can be specified.
More broadly often they will use rough names that indicate the general type of the thing, rather than struct type signatures.
This is particularly relevant when documenting a function not a method.
As it lets you be a bit more expressive about what things are
Personally, for internal function I often omit the signature line.
And often put docstring all on one line
Here the docstring really is just a tiny increment better than a normal comment.
"foos the bar"
foo!(bar) = bar*bar*2