Should every method in Base be documented?

question

#1

Is the Julia developers’ policy that every method in the Base module should be documented, or that in order to avoid clutter, it’s okay to omit documentation for methods that are fairly minor variants on other, documented methods?

In this issue I pointed out some counterintuitive behavior in an undocumented Base method. A core developer made a PR that fixed the behavior but still didn’t include a docstring, and didn’t respond when I asked about that.

(I hope that this question doesn’t come across as nitpicking or complaining - I have no preference whether or not the method in question gets included in the documentation, I’m just curious about the documentation policy for future reference.)


#2

Obviously it would be a lot of work that no one has time for right now, but I think having a least a few words of documentation per function seems reasonable?


#3

I actually have no idea what fraction of the Base methods are already documented. Guess that probably wouldn’t be too hard to check.


#4

Every exported name should have documentation. Every function should clearly state its generic behavior. Any method that does something that might be considered surprisingly different from the general definition should call it out.

In this specific case, I’m not terribly worried about that specific ::Char method — it fits rather nicely with the general parse definition. Sure, it calls its argument str and string, but, eh, I think it’s fairly obvious how this method would work given the generic help text. I wouldn’t consider the ::Char behavior surprising.


#5

I think the general goal is not to have a docstring for each method, but to try to design functions such that the behavior is generic across some set of types. So we don’t have separate docstrings for +(a::Int,b::Float) and +(a::Int,b::BigInt). In this case the function parse(type, str, [base]) contains the method you are talking about. I think the behavior is intended to be the same if str is a one character String or a Char. At most it seems like a note somewhere that it accepts strings or chars may be worthwhile.

You can find it in the docs here (make sure to be on latest!): https://docs.julialang.org/en/latest/base/numbers/#Base.parse

And if you click the “source” link you’ll be taken here: https://github.com/JuliaLang/julia/blob/049b9bc91241066288f3c34066b4f9b2495ff843/base/parse.jl#L7-L33

Oddly, you can’t click the “edit” button from that link because you aren’t on a branch. So you can scroll up and choose master, and find the same part, which gets you here: https://github.com/JuliaLang/julia/blob/a55c280d1b28a4cb069b43cb5691ec8a3b248801/base/parse.jl#L7

From there you can hit the little pencil button in the top right to edit it. If you feel like you have improved it, it’s easy to submit a Pull Request through the Github UI.


#6

Got it. After the PR linked to above, the behavior of parse(Type::, Char::) is no longer surprising. It certainly was surprising (to me, at least) when parse(Int, 'a') and parse(Int, "a") had completely different behavior.


#7

Method documentation is very good up to a point. I still find myself calling methods(some_function_name) on a regular basis to find the exact method signatures. I do this in Jupyter and the links to the source code for each method are really helpful. My thanks to the person who had the idea to provide such links and to the people who ended up implementing that feature.


#8

Note that it is also possible to jump to the source code from the REPL on Julia v0.7