Document the shuffle function

Author: RaimoNiskanen

lib/stdlib/src/rand.erl

@@ -1317,13 +1317,35 @@ normal_s(Mean, Variance, State0) when 0 =< Variance ->
     {Mean + (math:sqrt(Variance) * X), State}.
 
 
--spec shuffle(list()) -> list().
+-doc """
+Shuffle a list.
+
+Like `shuffle_s/2` but operates on the state stored in
+the process dictionary.  Returns the shuffled list.
+""".
+-doc(#{group => <<"Plug-in framework API">>,since => <<"OTP 29.0">>}).
+-spec shuffle(List :: list()) -> ShuffledList :: list().
 shuffle(List) ->
     {ShuffledList, State} = shuffle_s(List, seed_get()),
     _ = seed_put(State),
     ShuffledList.
 
--spec shuffle_s(list(), state()) -> {list(), state()}.
+-doc """
+Shuffle a list.
+
+From the specified `State` shuffles a list
+so that every element in `List` has an equal probability
+to be shuffled into every position in `ShuffledList`.
+
+Returns the shuffled list [`ShuffledList`](`t:list/0`)
+and the [`NewState`](`t:state/0`).
+""".
+-doc(#{group => <<"Plug-in framework API">>,since => <<"OTP 29.0">>}).
+-spec shuffle_s(List, State) ->
+          {ShuffledList :: list(), NewState :: state()}
+              when
+      List         :: list(),
+      State        :: state().
 shuffle_s(List, {#{bits:=_, next:=Next} = AlgHandler, R0})
   when is_list(List) ->
     WeakLowBits = maps:get(weak_low_bits, AlgHandler, 0),