I think it would be great if there was some official syntax for specifying a docstring directly for function arguments. “Official”, as in, the information should be readable by third-party packages like Juno, to build tooling on top of.
As it stands, you get at most two pieces of information when typing in a function name and seeing the list of arguments (in Juno). That is the argument name and its type. But often, the arguments are named in a way that does not explain what they are about. Sometimes you might infer the meaning from the type restriction, but often there is none. Let’s say you want to execute a function
model() and you type it in, when you see this:
Now you don’t really know much unless you are a domain expert and know already what the greek letter stands for or what qef means (I made these up). You also don’t know what will happen to the kwargs when you supply any.
In Swift, for example, there are argument labels, which help understanding what the arguments of the function are for. I’ve always found those labels quite useful. Here’s an example from their docs:
Even though it’s already useful, a one-word label is very limited (although it has to be used when calling the function, so it is a more strict requirement than I would like). Maybe something like this would be better:
function model( μ::Real, # The amount of damping applied to the model qef::Rational; # The quantum entanglement factor kwargs... # kwargs will be forwarded to `compute_model()` )
Or even as real docstrings, so they exist as julia objects, are therefore more easily accessible for third party packages, and interpolation works:
function model( μ::Real, "The amount of damping applied to the model" qef::Rational; "The quantum entanglement factor" kwargs... "Kwargs will be forwarded to `compute_model()`" )
A counterargument I can imagine would be “This is what the function docstring is for”, but I believe there is a case for a short description that belongs directly to the argument. The function docstring could then expand on the meaning of the variable even more, but the time needed to understand the arguments would be much less in my opinion, if a short explanation was directly available. The full function docstring is quite a long text if you have many arguments, and people will probably not want to read it every time they want to know something about a parameter.
Imagine hovering the cursor over a function argument in some code you don’t understand yet, and a tooltip pops up that just displays this argument docstring.
This syntax could even simplify writing the function docstring itself, because it could be appended in a nicely formatted way to the main function. At least I am usually too lazy to copy argument names to the docstring and nicely format a list of descriptions (also because I often forget updating the docstring when I change the argument name later).