Clarify definition of cyclic permutation in randcycle docstring (#50487)

Author: stevengj

stdlib/Random/src/misc.jl

@@ -345,6 +345,12 @@ Construct a random cyclic permutation of length `n`. The optional `rng`
 argument specifies a random number generator, see [Random Numbers](@ref).
 The element type of the result is the same as the type of `n`.
 
+Here, a "cyclic permutation" means that all of the elements lie within
+a single cycle.  If `n > 0`, there are ``(n-1)!`` possible cyclic permutations,
+which are sampled uniformly.  If `n == 0`, `randcycle` returns an empty vector.
+
+[`randcycle!`](@ref) is an in-place variant of this function.
+
 !!! compat "Julia 1.1"
     In Julia 1.1 and above, `randcycle` returns a vector `v` with
     `eltype(v) == typeof(n)` while in Julia 1.0 `eltype(v) == Int`.
@@ -367,10 +373,16 @@ randcycle(n::Integer) = randcycle(default_rng(), n)
 """
     randcycle!([rng=default_rng(),] A::Array{<:Integer})
 
-Construct in `A` a random cyclic permutation of length `length(A)`.
+Construct in `A` a random cyclic permutation of length `n = length(A)`.
 The optional `rng` argument specifies a random number generator, see
 [Random Numbers](@ref).
 
+Here, a "cyclic permutation" means that all of the elements lie within a single cycle.
+If `A` is nonempty (`n > 0`), there are ``(n-1)!`` possible cyclic permutations,
+which are sampled uniformly.  If `A` is empty, `randcycle!` leaves it unchanged.
+
+[`randcycle`](@ref) is a variant of this function that allocates a new vector.
+
 # Examples
 ```jldoctest
 julia> randcycle!(MersenneTwister(1234), Vector{Int}(undef, 6))
@@ -390,6 +402,7 @@ function randcycle!(r::AbstractRNG, a::Array{<:Integer})
     n == 0 && return a
     a[1] = 1
     mask = 3
+    # Sattolo's algorithm:
     @inbounds for i = 2:n
         j = 1 + rand(r, ltm52(i-1, mask))
         a[i] = a[j]