News for hackers. Stuff that matters.
Re:Rust explained using easy English by giancarlostoro on Thursday July 23, 2020 @10:55AM (#23927973)
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.

Re:Rust explained using easy English by spoiler on Thursday July 23, 2020 @11:09AM (#23928129)
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.

Re:Rust explained using easy English by tome on Thursday July 23, 2020 @11:41AM (#23928498)
> 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.

Re:Rust explained using easy English by giancarlostoro on Thursday July 23, 2020 @11:14AM (#23928183)
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.
Re:Rust explained using easy English by s_c_r on Thursday July 23, 2020 @06:29PM (#23933344)
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.
Re:Rust explained using easy English by joshmarlow on Thursday July 23, 2020 @12:53PM (#23929346)
>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

Re:Rust explained using easy English by giancarlostoro on Thursday July 23, 2020 @03:14PM (#23931116)
Kinda sad it looks like that was last updated 2 years ago
Re:Rust explained using easy English by masklinn on Friday July 24, 2020 @03:09PM (#23943336)
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.

Re:Rust explained using easy English by giancarlostoro on Monday July 27, 2020 @09:55AM (#23965104)
My main concern is if Rust changes significantly in a few years and this utility breaks then.
Re:Rust explained using easy English by joshmarlow on Tuesday July 28, 2020 @10:16AM (#23976008)
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.
Re:Rust explained using easy English by pornel on Thursday July 23, 2020 @11:46AM (#23928567)
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.

Re:Rust explained using easy English by giancarlostoro on Thursday July 23, 2020 @12:21PM (#23928992)
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...
Re:Rust explained using easy English by pornel on Thursday July 23, 2020 @04:31PM (#23931908)
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.
Re:Rust explained using easy English by giancarlostoro on Monday July 27, 2020 @12:47PM (#23966838)
That's great to know, might have to revisit it now that I'm back experimenting with Rust.