Argument-specific docstrings or comments

Internals & Design
21

I have something similar that I use in Juno, would be good with a native atom solution though
https://github.com/baggepinnen/AutomaticDocstrings.jl
I have an atom script that does almost the same thing, but my Javascript skills are nonexistent so I didn’t really get it all the way, code in this issue
https://github.com/JunoLab/atom-julia-client/issues/519

22

I also hate that when I update a function, I forget to update the docstring because it’s not synced. I once tried inline docstrings like this not knowing that it wasn’t allowed, so I assume this format/syntax is the most intuitive:

function some_function_name(
        "Some argument description."
        a::Int,
        "Another argument description."
        b::String = "default"
)
    # Do something
end

How I would expect the docstring to appear is something like in Excel or @MartinOtter’s reply:

f(|

f(a::Int [, b::String])
Some argument description.

f(1, |

f(a::Int, b::String)
Another argument description.
Default: "default"

(How exactly the docstring is presented is secondary, this example is just for illustration.)

Argument docstrings should be relatively short, they are not the right place to cram in a whole manual. They’re also not meant to replace other docstrings, just to enhance them. With modern editor support, I don’t expect any code readability issues—on the contrary, you find the right information in the right amount at the right site.

23

Instead of a docstring-only solution, wouldn’t it be better to have a more general solution to attach arbitrary attributes (potentially more than one) to any language element?

Ideally, the mechanism would be the same for variables, functions, function arguments etc.

These attributes could then be used by an external typechecker to implement e.g. refinement types, as recently discussed here Would it make sense for Julia to adopt refinement types?.

1 Like
24

Or Java’s annotations.