Documentation organisation

[dhardy]

Just a heads up: I've been working on The Book.

You may notice a lot of overlap with the current API docs: my plan is to reduce the wordiness of the API docs significantly to make them easier to browse, especially the module documentation for the lib (top-level), rngs and prng.

The book has lots of links into the API docs (via relative links; seems to work fine as hosted and locally with a simple symlink). The API docs should in theory link into the book too; I'm not sure the best way of doing this since I don't want to break our cargo deadlinks CI testing.

About testing: this is unfortunately a big step backwards since MdBook fails on most examples with linker errors; additionally the "run" command on the book's snippets doesn't appear to handle imports via use correctly (if it works at all). Link checking is probably possible (though it may not be trivial to make those relative links to the API work in CI testing). See https://github.com/rust-random/book/issues/2.

There's still a lot to do here, though most of the Guide section is ready for proof-reading. I'm not sure about the Overview section.

[vks]

Looks good! A few comments:

• Random data:

  Now lets take a silly example: the natural numbers (1, 2, 3, etc.). These numbers have no limit. So if you were to ask for an unbiased random natural number, 1, 5, 1000, 1 million, 1 trillion — all would be equally likely. Since there is no upper bound here, the expected value (the "average" value) is infinitely large. So maybe this isn't useful to us.

  BigInt: since this type has no upper bound, we cannot produce an unbiased random value (it would be infinitely large, and use infinite amounts of memory)

  I think this should be slightly reworded: There is no unbiased/uniform distribution of the natural numbers. You can only define a uniform distribution on finite intervals.

  In general, I would prefer a more mathematical approach. In my opinion, when explaining "random data", distributions should be introduced. The distinction between uniform and non-uniform distributions would also make the whole discussion less vague.

• Since from our point of view these things are unpredictable and we require some source of entropy, we are forced to assume that at least some such processes are truely random.

  Nitpick: It is enough if they are not distinguishable from true randomness.

• psuedo-random number generators

  I think the correct spelling is "pseudo"?

• A hardware random number generator (HRNG) may be a TRNG or a PRNG or some combination of the two.

  This does not really say much. Maybe mention why you would prefer a hardware RNG over software one?

• I think Random values should mention that it is about uniform sampling and mention sample as a generalization.

• In Random distributions, the distinction between "More continuous distributions" and "Probability distributions" seem arbitrary. Maybe merge the sections?

• This is a trick question: we need to know both the range we want and the type of distribution of this value (which is what the next section is all about).

  Nitpick: The range is part of the distribution.

• It seems it is never explained what a distribution is.

[dhardy]

Thanks for proof reading!

In general, I would prefer a more mathematical approach.

True. In the aim of keeping the material as accessible as possible I tried to minimise expected background knowledge and leave distributions until later (section 2.5), but this doesn't work out so well. Point noted.

This does not really say much. Maybe mention why you would prefer a hardware RNG over software one?

To be honest I'm not sure what to say. Quite often a software RNG is preferable for speed and reliability anyway.

In Random distributions, the distinction between "More continuous distributions" and "Probability distributions" seem arbitrary. Maybe merge the sections?

Is it? It may not be well worded, but three of the listed "probability distributions" are discrete, and I believe the latter often used in models to sample a probability value. Suggestions welcome but I think there should be some kind of distinction here.

(Note that many distributions such as Gamma and Weibull are not listed simply because I assume that people who want to use them will already know exactly which distribution they want and peruse the API docs; the main purpose of this listing is to help inexperienced modellers find something appropriate, though of course it is woefully short of a proper introduction to modelling.)

Nitpick: The range is part of the distribution. It seems it is never explained what a distribution is.

It's certainly a property of the parameterised distribution but not of the type of distribution. Seems a little work is needed here.

[dhardy]

Please review: https://github.com/rust-random/book/pull/3

[dhardy]

I think this can be closed now.