Uhm. Yes they are.
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”.
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.
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!
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.
