A bit more work on the readme #437
Conversation
README.md
Outdated
| * [rand_core](https://crates.io/crates/rand_core) | ||
| Part of the functionality of Rand lives in the [rand_core]( | ||
| https://crates.io/crates/rand_core) crate, which is not intended for users but | ||
| primarily for crates implementing RNGs. |
There was a problem hiding this comment.
I don't like this style much. We will probably have more sub-crates shortly so a list is a good presentation, and then a description something like:
core generation traits; this crate is most useful when implementing RNGs
There was a problem hiding this comment.
I have changed the text a bit, but shall we wait switching to a list until it contains more than one item?
There was a problem hiding this comment.
If you like. But you're the one switching here.
There was a problem hiding this comment.
I never really understood the bullet point, it seemed to be for some kind of stylistic emphasis. Only now I get it was meant to be the first item of what should become a list.
README.md
Outdated
| [master branch](https://rust-lang-nursery.github.io/rand/rand/index.html), | ||
| [by release](https://docs.rs/rand) | ||
| [by release](https://docs.rs/rand). |
There was a problem hiding this comment.
Considering what docs.rs is doing at the moment, it may be best to link directly to the current minor version; i.e. docs.rs/rand/0.5 for the next release (doesn't work at the moment, but 0.4 does so should be fine for the release).
README.md
Outdated
| use rand::prelude::*; | ||
|
|
||
| // basic usage with random(): | ||
| let x: u8 = rand::random(); |
There was a problem hiding this comment.
don't need rand:: prefix with the prelude
There was a problem hiding this comment.
If we advertise random so prominently, shouldn't we also mention the caveats?
There was a problem hiding this comment.
Which do you have in mind to mention?
There was a problem hiding this comment.
That calling random often is not recommended, because it is more efficient to reuse the RNG.
There was a problem hiding this comment.
Not here, no: (1) premature optimisation (actually there's not a big overhead anyway); (2) it's in the random doc and keeps this simple.
README.md
Outdated
| - Functionality for seeding PRNGs: the `FromEntropy` trait, and as sources of | ||
| external randomness `EntropyRng`, `OsRng` and `JitterRng`. | ||
| - Most content from `rand_core` (re-exported): base random number generator | ||
| traits and error-reporting types. |
There was a problem hiding this comment.
You want to say this without explaining what rand_core is? Not sure whether there should be a section in this README; otherwise maybe link to https://crates.io/crates/rand_core.
There was a problem hiding this comment.
It is linked above?
README.md
Outdated
|
|
||
| There is a compatibility shim from 0.3 to 0.4 forcibly upgrading all Rand 0.3 | ||
| users; this is largely due to the small differences between the two versions. | ||
|
|
||
| ### Rust version requirements | ||
|
|
||
| The 0.5 release of Rand will require **Rustc version 1.22 or greater**. |
There was a problem hiding this comment.
Might as well get this right for the actual release now? will require → requires; also maybe remove the below?
README.md
Outdated
| functionality depending on `std`: | ||
|
|
||
| - `thread_rng()`, and `random()` are not available, as they require thread-local | ||
| storage. |
README.md
Outdated
|
|
||
| - `thread_rng()`, and `random()` are not available, as they require thread-local | ||
| storage. | ||
| - `OsRng` is unavailable. |
There was a problem hiding this comment.
and EntropyRng
Is it worth linking to #313 somewhere?
There was a problem hiding this comment.
We could. Is it important enough for the readme?
pitdicker
force-pushed
the
simplify_readme
branch
from
e281dd3 to
f0dcebb
Compare
|
Actually, better not to merge until we're ready to release 0.5 because until then the doc link is broken. |
Changes:
rand_coreless prominently.random();rand_coreless here.Rendered.