add few comments

base/random/RNGs.jl

@@ -2,7 +2,7 @@
 
 ## RandomDevice
 
-# SamplerTypes(Union{X,Y,...}) = Union{SamplerType{X},SamplerType{Y},...}
+# SamplerTypes(Union{X,Y,...}) == Union{SamplerType{X},SamplerType{Y},...}
 SamplerTypes(U::Union) = Union{map(T->SamplerType{T}, Base.uniontypes(U))...}
 const SamplerBoolBitInteger = SamplerTypes(Union{Bool, Base.BitInteger})
 

base/random/generation.jl

@@ -2,6 +2,17 @@
 
 # Uniform random generation
 
+# This file contains the creation of Sampler objects and the associated generation of
+# random values from them. More specifically, given the specification S of a set
+# of values to pick from (e.g. 1:10, or "a string"), we define
+#
+# 1) Sampler(rng, S, ::Repetition) -> sampler
+# 2) rand(rng, sampler) -> random value
+#
+# Note that the 1) is automated when when the sampler is not intended to carry information,
+# i.e. the default fall-backs SamplerType and SamplerTrivial are used.
+
+
 ## from types: rand(::Type, [dims...])
 
 ### random floats

base/random/random.jl

@@ -95,6 +95,10 @@ Base.getindex(st::SamplerSimple) = st.self
 
 ### machinery for generation with Sampler
 
+# This describes how to generate random scalars or arrays, by generating a Sampler
+# and calling rand on it (which should be defined in "generation.jl").
+# NOTE: this section could be moved into a separate file when more containers are supported.
+
 #### scalars
 
 rand(rng::AbstractRNG, X) = rand(rng, Sampler(rng, X, Val(1)))