search

rust-random / rand

A Rust library for random number generation.
https://crates.io/crates/rand
Other
1.67k stars 431 forks source link

rand_pcg has zero usage examples #1347

Closed kornelski closed 6 months ago

kornelski commented 1 year ago

The crate page for rand_pcg has no code examples. It links to documentation, but it's a documentation of implementation details of the algorithm, rather than how to actually use any of this crate's functionality. As far as I can tell, there is not a single piece of code demonstrating generating a random number anywhere in the crate's docs.

Everything about this crate assumes the user is already familiar with the rand crate. However, from rand's docs it's not obvious how to use the other algorithms with it either. The Additional generators section just lists them, but has no code examples, and it just links back to code-less docs of rand_pcg and others, which feels like a catch 22.

The key to this puzzle is very hard to spot. Everything user needs to know is folded hidden, and sandwiched between implementations of irrelevant traits, camouflaged to look like boilerplate lists:

Screenshot 2023-10-25 at 02 52 52

dhardy commented 1 year ago

So you'd like documentation to link explicitly to those RNG traits and include a small example? Sure, please do.

The reason rand_pcg feels like an unwanted-extra is because it was once used to implement SmallRng but is no longer used for that purpose, leaving it as "just another RNG".

vks commented 1 year ago

I guess that is a common problem in Rust, where functionality is often "hidden" in traits. I think a "quick start" example would help with this.

dhardy commented 1 year ago

Wait, this is about doc links not just examples...

dhardy commented 1 year ago

@vks could you attach a little more doc to the RNGs in your examples PRs please? Something like this:

This is a Random Number Generator. A new instance of the RNG may be created and seeded through the [SeedableRng] trait. While the [RngCore] trait supports basic value generation, we recommend usage of the rand crate and its Rng trait for additional functionality.

This is a [Random Number Generator](https://rust-random.github.io/book/guide-gen.html). A new instance of the RNG may be created and seeded through the [`SeedableRng`] trait. While the [`RngCore`] trait supports basic value generation, we recommend usage of the [`rand` crate](https://crates.io/crates/rand) and its [`Rng` trait](https://docs.rs/rand/latest/rand/trait.Rng.html) for additional functionality.