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.)
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?
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.
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.
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.
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.
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.