I just checked again, and apparently they finally added some documentation since I last checked. The section about the macro stuff just used to say “look at the examples”.
What value is this blog supposed to be adding exactly?
The fact that top-level and API descriptive explanations are important?
The fact that some projects don’t have complete documentation?
To whom exactly would this be considered new information?
This. I can’t count HOW MANY FUCKING TIMES I had to either look up the source code or search GitHub for code using a function from a given library because the documentation was so laconic and/or disjointed.
My absolute favourite is when the examples say something like “production code should not be written like this, this is just for clarity” with no indication of what’s wrong with the code.
Is it just normal Rust stuff like there’s unwraps everywhere and it’s one big file? Does the example have security or performance problems? Is the example unidiomatic or over-verbose or is it ignoring features real-world code would use? EXPLAIN YOURSELF!
I personally prefer the straight forward everything in one file examples. The worst examples are those that come with its own ad hoc example framework I first need to understand before I can understand the example.
It’s probably to encourage people to underdtsnd the example properly then write their own code. Too many people copy/paste examples without understanding them completely.
Add comment