Improve random documentation

[Steven Watanabe]

Robert Ramey wrote:

Since you asked. I think my problem is in the very first section under the title "Boost Random Number Library".

I expected to find and example like:

normal_distribution nd<int>(mean, standard_deviation)
...
int random_number = nd();
...

Of course I realized pretty soon that I wasn't going to find that. So then I looked at the random_demo.cpp which was helpful and led me to look at library headers which wasn't all that helpful.

Personally I would have found a small tutorial helpful. for example:

The random number library is composed of:

"generators" which generate random numbers and "distributors" which transform output from a "generator" into a particular distribution:

A small complete example (from random_demo.cpp)

// simulate rolling a die 10 times

// construct a random simple random number generator
boost::minstd_rand random_number_generator;

// construct a uniform distribution for integers 1 through 6
boost::uniform<int> uniform_distribution(1,6);

// hook the above together to create a die?
// I'm not sure what to call this "variate_generator" didn't help me at all
boost::variate_generator<boost::minstd_rand &, boost::uniform<int> & > die()

// throw the die 10 times
for(int i = 0; i < 10; ++i)
    std::out << die() << '\n'

Notice the lack of typedefs and other stuff to make things more abstract". I eliminated these to make the example less ... uh abstract.

To summarize, a little bit more introduction would have helped me get going faster.

[Steven Watanabe]

I've completely overhauled the docs now. The changes are scheduled to be released in 1.43.