I don't understand people recommending reading the source code to learn. Source codes can be really daunting because there are so many things going on. There can also be "tricks" using advanced language features, which defeats the purpose if you're trying to learn as a first timer. Also, "read the source" is, at least to me, an admission that there is no valid documentation 90% of the time. Reading the source of a tool or a small to medium library is fine, it's not fine for large projects or projects you know nothing about.
Incremental examples is where it's at. You should document a fonction/type/feature/whatever with a short example with basic operations and then a more involved example with good practices and potential caveats. I know this is a lot of work, I understand it can't be like that everywhere.
This is not a dig at anyone's project or language, but "read the source code" comments always strike me as unhelpful.
Incremental examples is where it's at. You should document a fonction/type/feature/whatever with a short example with basic operations and then a more involved example with good practices and potential caveats. I know this is a lot of work, I understand it can't be like that everywhere.
This is not a dig at anyone's project or language, but "read the source code" comments always strike me as unhelpful.