First of all, I must apologize, in advance, for the blunt language below. I’m not going to accuse anybody. I’ll just try to describe the problems I’ve encountered.
I have been using Julia for 1.5 years (and I’m sorry to skip great things about Julia) and the greatest difficulty in using Julia is the general “lack” of “manuals”.
Tutorials are excellent. But, to find out details of the arguments to library functions is sometimes extremely hard.
Most of julia’s core standard functions are very general and as a result, the most “accurate” description of the API must needs be abstract. For example,
Base.findall is described (defined) as
Return a vector
trueindices or keys of
There is no clue (to a newcomer) what
A is expected to be.
The examples given there all use a vector for From some of the examples given there, I got the (incorrect) impression that the
A must be an array or vector. After a 1.5-year experience with Julia, I can tell that ranges and many more collections can works as
But, when I was a complete newbie, I naïvely thought that a vector is expected and wrote
findall(somecondition, collect(1:10)) in an example code in the Discourse. Then, a seasoned programmer lectured me that
collect() should almost never be used. I asked why and where the API of
findall is documented. Then I was shown to the source code!
The current state of documentation seems to be
- the “accurate” description,
- source code,
- or nothing.
But, what most regular users need is something between 1 and 2: a “helpful” description of the API using an informal language (convention). For example, the
A argument of
findall is an “indexable collection like a vector or dictionary”, which would be linked to a discussion of generally what datatypes are indexable, where it would be explained that a Range like 1:10 is also indexable.
Here is another example of a different flavor. I was trying to find out how to specify color schemes for contour plots. I googled for “julia Plots contour color schemes” and found the excellent official documentation of color schemes:
except that it doesn’t tell you how to use those
cgrads objects and the “pre-defined color schemes” with the
So, I looked at the documentation of the
The only example it includes is the
color=:turbo style. Where are the
cgrad objects? Confusingly, I found another example
fill = (true, :ranbow) on another website.
The problem here is that there is no API description of the
contour function at one place. Or there may be one somewhere, which I haven’t been able to locate.
An example based description is excellent for a tutorial but it’s not adequate as a “manual”.