4 ms·
I'm picking up Rust again, and one of our lead architects tried to pick it up but ran into the same issues I've ran all along: third party libraries (even extre
by giancarlostoro 6y ago
I'm picking up Rust again, and one of our lead architects tried to pick it up but ran into the same issues I've ran all along: third party libraries (even extremely popular ones) have outdated example code or docs that are inconsistent with actually released versions. So in the meantime I will focus on learning the out of the box features of Rust.
It is a shame because I love the potential of Rust but it seems that not much has changed in the two years since I last touched it in the regards to documentation for external projects. I still am not good enough with Rust to start producing my own projects as a result, which in other languages you can do rather quickly. I hope the ecosystem matures in this regard because I love everything else, the tooling, the build system is very modern and mature as best as I can tell.
- spoiler 6y agoThe issues with documentation aren't really something I'd attribute to the Rust ecosystem, but just to people/humans in general. I've had this problem with every language I worked with: JS/TS, Haskell, C/C++, Go. Eg,the C++ boost docs are IMO completely decrepit, but people still manage to be productive using it. If you see a mistake in the docs, open an issue (or a PR), it only costs you little time.
- giancarlostoro 6y agoMost of my contributions on GitHub are tickets, so I just might have to. Thing is I have a rule of thumb that if I can't get a language to work in about 15 minutes, I ditch it. But now that I do want to get into Rust I may just have to write up tickets when I run into issues.
- tome 6y ago> I've had this problem with every language I worked with: ... Haskell ... By the way, if you see outdated Haskell docs please report them on https://github.com/tomjaguarpaw/tilapia https://github.com/tomjaguarpaw/tilapia. I am (slowly) collecting examples and trying to improve the ecosystem.
- pornel 6y agoFile bugs for these! I wouldn't be surprised if readmes were rotten, but you should be able to rely on examples in docs and example programs in Cargo projects, because they are automatically built and run during unit tests.
- giancarlostoro 6y agoThat's interesting I didn't even think about that, then I'm not sure why it doesn't work. One case I still remember was where Actix (web framework) had docs pointing to severely older versions of the software, while the readme pointed to another, and none of them matched up quite right at the time... It was just not useful. If the examples work but you don't know where to go from there what can you even do at that point...
- pornel 6y agoActix had a major rewrite when it moved from old futures to new async/await model, so for a while there was a big difference between released/stable 0.x version and new shiny/dev 1.x version. Now it has mostly settled down.
- giancarlostoro 6y agoThat's great to know, might have to revisit it now that I'm back experimenting with Rust.
- joshmarlow 6y ago>third party libraries (even extremely popular ones) have outdated example code or docs that are inconsistent with actually released versions. That's actually one of my big pet-peeves about OSS. This is especially annoying because the Rust ecosystem already has a really nice solution to the problem - skeptic ([0]). Skeptic finds Rust snippets in markdown files and dynamically builds tests to run them. So if your docs go out of sync with your code, `cargo test` fails. [0] - https://github.com/brson/rust-skeptic https://github.com/brson/rust-skeptic
- giancarlostoro 6y agoKinda sad it looks like that was last updated 2 years ago
- masklinn 6y agoskeptic should only be useful for arbitrary markdown files though, `cargo test` should run the docstring snippets. The example snippets are more difficult to craft though, as they need to be "self-contained" and you need to hide the bits you don't want to show by marking them as a pseudo-comment using `#`. Rustdoc also has a `--test` flag. Tested it on clap (no specific reason, just have a checkout locally) and it ran 314 snippets from the docs so seems to work.
- giancarlostoro 6y agoMy main concern is if Rust changes significantly in a few years and this utility breaks then.
- joshmarlow 6y agoThat's a reasonable concern. IMO, a tool like Skeptic would add a lot of value to the ecosystem if deployed widely. It would be really cool if something equivalent was integrated into cargo.
- s_c_r 6y agoThis happened to me the other day with sqlx. Tried to duplicate the quick start example and got a slew of errors. I should make a ticket, maybe I did something wrong.