Hacker News Reader

Comment by giancarlostoro | Hacker News Reader

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.

View on HN

The 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.

Most 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.

> 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. I am (slowly) collecting examples and trying to improve the ecosystem.

This 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.

>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

Kinda sad it looks like that was last updated 2 years ago

skeptic 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.

My main concern is if Rust changes significantly in a few years and this utility breaks then.

That'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.

File 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.

That'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...

Actix 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.

That's great to know, might have to revisit it now that I'm back experimenting with Rust.

Reply on news.ycombinator.com