Hello I am writing a small little package and now I am editing the documentation strings. My question is the following:
Which of the following two is the preferred/most idiomatic in Julia?
First:
"""
`cyclotron{T<:AbstractFloat}(p::AbstractParticle{T}, ω::T)`
Return center and radius of circular motion performed by the particle based on
p.pos and p.vel.
"""
or second:
"""
`cyclotron(p::AbstractParticle, ω)`
Return center and radius of circular motion performed by the particle based on
p.pos and p.vel.
"""
In the second example I am removing the parametric type information.
Depends on what your users need to know about when reading your docs. If T is an important parameter that the user has to be aware of when calling cyclotron then probably best to include it and also mention it within the body of the docstring. If it’s not useful for the user to know about it then I’d say just leave it out to make the signature simpler to read.
Do note that the signatures that appear at the top of docstrings don’t need to be exact copies of the actual method signatures at all. They are just there to tell the user enough to be able to call the method successfully. Also, if you’d like to have Julia write the signatures for you itself then the following package might be of some use