How to write documentation which could be tested

1

Hi all! in all my time using Rust, there is one point that has been hard to use... and is documentation.

Rust is very explicit in how it works, which helps to understand how to look on documentation, but there is one point, the examples, they are not compiled, just works as any documentation, so the issue is when we go to examples and we found they are outdated or with problems.

So, maybe the crates I have checked need to improve documentation or this feature is not available (the latest one I checked is how get sample from probabilities in statrs crate).

Is there a way to write examples and code in documentation where each section is compiled?

Thx!

2

Examples (in the examples folder of a crate) do need to be tested separately, but it's usually simple for contributors to do. It can be done in CI, too.

However, code in documentation is already tested automatically when running cargo test. So if those are not working, it's either by ignoring the tests or testing in a different configuration than you. Perhaps you haven't enabled a feature?

3

No idea, I do not own statrs, was just weird that from time to time, when I see crates the test fails that much, as example:

The "Sampling" section don't works.

Maybe that crates just have a wrong configuration?

4

You likely have rand 0.9, which is brand new. statrs depends on 0.8. I wish crates would export their dependencies so that this didn't happen, but this is what we've got.

5

mm, I see, which is different from what happened in other crate I checked time ago.

I think be able to export the dependency (not do by default) would be nice.

And also, this seems a lot to be a Rust problem, because cargo should be able to know when you are using a lib from a incompatible version, would be a similar analysis to the upgrade one.

Is there a request a feature for this? rust-analyzer really give us very confusing/wrong messages when this happens.

1 Like
6

I found this thread which has some links.

There's a clippy lint for detecting duplicates. But it's difficult to make a good solution because duplicate dependencies are sometimes correct.

1 Like
7

There is an accepted RFC for distinguishing "public" and "private" dependencies, which would help with this. A lot of work has already gone into its implementation, but I think it's not clear yet when this functionality will be stabilized.

2 Likes
8

mm, I think for now, the best which could simplify or life, would be a fix on rust-analyzer, because the error message is wrong which caused most of this confusion.

9

I was thinking, this can also be solved in other way, the docs...............

They should show which versions are they using to run the examples, that would helps a lot too!