Deprecate gen_iter and add iteration examples

[dhardy]

As discussed in #275, these changes are all that we need, I think.

I put this documentation on the Rng trait; I'm not quite sure if that's the best option. The library documentation at the top if lib.rs could also be revised, potentially.

[pitdicker]

Looks good to me! A bit sad for the time you spent figuring out and testing alternatives...

Shall I try to merge?

[dhardy]

Speaking of alternatives, there's still all your FP code in my experimental branch... have to figure out whether we'll use that at some point.

[burdges]

You could always add some convenience method in the future, so roughly like:

pub trait Rng: RngCore + Sized {
    ...
    fn samples_iter<T,D: Distribution<T>>(&mut self,dist: D) -> impl Iterator<item=T> {
        ::std::iter::repeat(()).map(|()| self.sample(&dist))
    }

I wrote &dist to avoid D: Copy or whatever. I'd imagine multiple reference layers get optimized into one reference, but not sure.