44
Examples are not Documentation
(nereux.blog)
Welcome to the Rust community! This is a place to discuss about the Rust programming language.
Credits
clap and bevy are big offenders there. It's really hard to learn how to use them due to this.
Are you kidding me? Clap has some of the best documentation of any crate.
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”.
Ah that explains it.
It sucks that there aren't (in my limited experience) a ton of engines out there with good documentation (at least that are built in Rust). I've started trying to build my own engine, but the complexity and time required are certainly a bit of a barrier, especially for the game I'm working on. (N.B. - The game is nowhere close to being in any sort of state to be shown, so please don't ask 😆)
My experience has been that good documentation is mostly something done if somebody gets paid for the work. People working on stuff in their spare time just don't care enough to document their project.
That, or they don't care enough to pick it back up if they ever drop it. Nothing hurts worse than forgetting what you're trying to do because you don't even comment your code.