I am learning a lot these days by reading the source code of various Julia packages. There are certain scenarios where I see certain things achieved in some packages - things that don’t seem to be documented anywhere.
It is always expected to have a knowledge gap between those who are familiarized with Julia’s internals and those who are learning the language “from outside” - using the documentation (like myself): but I feel this is especially true for Julia.
When reading some source code and comparing it with the code I write, I feel like we are using two different languages (and I understand that the “type” of code written for a package can differ greatly from the regular “application” code - but still).
A thing that I find exciting about reading the source code is the discovery of “unknown unknowns”: those nice surprises where you learn something that you didn’t even think was possible (and was never your purpose in searching for those). However, I think I would really like to have these “unknown unknowns” documented instead of having to stumble upon them by accident (because it makes me wonder how many hidden things are still there, and I will never find them).
Is this only my subjective experience? Or is there a real gap between the documentation and frequently used idioms in various packages?
I think my subjective experience is warranted if the following is true: “There is actually code written in such a way that somebody relying on the documentation alone would not be able to write.”
How do other people feel about this? Are there certain tips that you can offer so I can narrow this perceived gap?