update the docs for rand/rand! and add some related tests

Author: rfourquet

doc/stdlib/base.rst

@@ -3946,7 +3946,7 @@ Random number generation in Julia uses the `Mersenne Twister library <http://www
 
 .. function:: rand!([rng], A)
 
-   Populate the array A with random number generated from the specified RNG.
+   Populate the array A with random numbers generated from the specified RNG.
 
 .. function:: rand(rng::AbstractRNG, [dims...])
 
@@ -3960,9 +3960,13 @@ Random number generation in Julia uses the `Mersenne Twister library <http://www
 
    Generate a random number or array of random numbes of the given type.
 
-.. function:: rand(r, [dims...])
+.. function:: rand(coll, [dims...])
 
-   Pick a random element or array of random elements from range ``r`` (for example, ``1:n`` or ``0:2:10``).
+   Pick a random element or array of random elements from the indexable collection  ``coll`` (for example, ``1:n`` or ``['x','y','z']``).
+
+.. function:: rand!(coll, A)
+
+   Populate the array A with random values drawn uniformly from the indexable collection ``coll``.
 
 .. function:: randbool([dims...])
 

test/random.jl

@@ -26,6 +26,11 @@ rand!(MersenneTwister(0), A)
 @test A == [0.8236475079774124  0.16456579813368521;
             0.9103565379264364  0.17732884646626457]
 
+@test rand(0:3:1000) in 0:3:1000
+coll = {2, uint128(128), big(619), "string", 'c'}
+@test rand(coll) in coll
+@test issubset(rand!(coll, cell(10)), coll)
+
 # randn
 @test randn(MersenneTwister(42)) == -0.5560268761463861
 A = zeros(2, 2)