After thinking about docstrings from another post, I was wondering if the Julia Style Guide, particularly for Core, Base, and the standard libraries should be further specified, particularly for docstrings.
Perhaps a good place to start would be the SciML Style Guide. I’m particularly interested a more detailed convention for documentation. For example, should exported or public Base functions follow the example below taken from SciMLStyle?
"""
mysearch(array::MyArray{T}, val::T; verbose = true) where {T} -> Int
Searches the `array` for the `val`. For some reason we don't want to use Julia's
builtin search :)
# Arguments
- `array::MyArray{T}`: the array to search
- `val::T`: the value to search for
# Keywords
- `verbose::Bool = true`: print out progress details
# Returns
- `Int`: the index where `val` is located in the `array`
# Throws
- `NotFoundError`: I guess we could throw an error if `val` isn't found.
"""
function mysearch(array::AbstractArray{T}, val::T) where {T}
...
end
The one thing I might add here would be a Implements or Interfaces section.
The answer is YES. Early on, I believe the Julia devs were conservative and didn’t want to be overly prescriptive. The language has clearly matured, and the inconsistencies in docstrings and documentation now outweigh the theoretical pain from over-prescription.
It’s fine to be opinionated at this point, and to have guidelines for core/base. Likely there may be bits deep in the repo that’ll take years or never get updated, and that’s fine. But might as well standardize from now on and set an example for all to follow.
SciML has done a great job of leading the way. AFAIK there haven’t been any revolts. I would go as far as to recommend similar guidelines for all users. I often suffer pangs of doubt “am I doing this the right way?” that are not resolved by websearch. It’s okay to state an opinion without it sounding like Zen of Python. And eventually maybe even adopt the SciML guidelines on interfaces…
On top of that I would like this to hook into Documenter.jl, so it can read the docstring and nicely format it for me when rendering the docs. Python docs usually do this and it looks much cleaner in my opinion.
I think there are many good points in the SciML style guide, but I do not agree with this one in particular:
Prefer to not shadow functions
Two functions can have the same name in Julia by having different namespaces. For example, X.f and Y.f can be two different functions, with different dispatches, but the same name. This should be avoided whenever possible
in my view, trying to consolidate kinda-similar-kinda-not-really-the-same methods into the same function often leads to a whole lot of bugs that could be avoided if we were more willing to namespace functions per package!
I suspect that is mis-worded. SciML has overloaded solve everywhere, so do they intentionally re-use method names for a general concept. I believe they mean a couple things: Don’t use the same name for very different concepts, and perhaps don’t use a highly ambiguous or unhelpful name. And of course we can always use the module as a namespace, or import to be more explicit.
This is one of the things I noticed the most coming from Python. I’m not sure if its just because I have not dug deep enough in Documenter.jl or not, but at a surface level I didn’t notice a way to neatly document arguments and return types following the Documenter.jl guide. I really like the SciML style and it would be great to see it rendered like this into the generated documentation. It would also be good to see an example of a more complicated docstring make its way into the guide as well. When I first read it I wanted to know how to handle arguments and returned types but just assumed that wasn’t the norm in Julia.
