update documentation for rand_*, aimed at issue #4