include/ruby/internal/intern/random.h: add doxygen

Must not be a bad idea to improve documents. [ci skip]

include/ruby/internal/intern/random.h

@@ -30,13 +30,85 @@
 RBIMPL_SYMBOL_EXPORT_BEGIN()
 
 /* random.c */
+
+/**
+ * Generates a 32 bit random number.
+ *
+ * @return  A random number.
+ * @note    Now  that  we  have  ractors,  the  RNG  behind  this  function  is
+ *          per-ractor.
+ */
 unsigned int rb_genrand_int32(void);
+
+/**
+ * Generates a `double` random number.
+ *
+ * @return  A random number.
+ * @note    This function shares the RNG with rb_genrand_int32().
+ */
 double rb_genrand_real(void);
+
+/**
+ * Resets the RNG behind rb_genrand_int32()/rb_genrand_real().
+ *
+ * @post  The (now per-ractor) default RNG's internal state is cleared.
+ */
 void rb_reset_random_seed(void);
+
+/**
+ * Generates a String of random bytes.
+ *
+ * @param[in,out]  rnd  An instance of ::rb_cRandom.
+ * @param[in]      n    Requested number of bytes.
+ * @return         An instance of ::rb_cString, of binary, of `n` bytes length,
+ *                 whose contents are random bits.
+ *
+ * @internal
+ *
+ * @shyouhei doesn't know if this is an  Easter egg or an official feature, but
+ * this function can  take a wider range of objects,  such as `Socket::Ifaddr`.
+ * The arguments are just silently ignored and the default RNG is used instead,
+ * if they are non-RNG.
+ */
 VALUE rb_random_bytes(VALUE rnd, long n);
+
+/**
+ * Identical to rb_genrand_int32(), except it generates using the passed RNG.
+ *
+ * @param[in,out]  rnd  An instance of ::rb_cRandom.
+ * @return         A random number.
+ */
 unsigned int rb_random_int32(VALUE rnd);
+
+/**
+ * Identical to rb_genrand_real(), except it generates using the passed RNG.
+ *
+ * @param[in,out]  rnd  An instance of ::rb_cRandom.
+ * @return         A random number.
+ */
 double rb_random_real(VALUE rnd);
+
+/**
+ * Identical  to  rb_genrand_ulong_limited(),  except it  generates  using  the
+ * passed RNG.
+ *
+ * @param[in,out]  rnd    An instance of ::rb_cRandom.
+ * @param[in]      limit  Max possible return value.
+ * @return         A random number, distributed in `[0, limit]` interval.
+ * @note           Note it can return `limit`.
+ * @note           Whether  the  return  value  distributes  uniformly  in  the
+ *                 interval or not depends on  how the argument RNG behaves; at
+ *                 least in case of MT19937 it does.
+ */
 unsigned long rb_random_ulong_limited(VALUE rnd, unsigned long limit);
+
+/**
+ * Generates a random number whose upper limit is `i`.
+ *
+ * @param[in]  i  Max possible return value.
+ * @return     A random number, uniformly distributed in `[0, limit]` interval.
+ * @note       Note it can return `i`.
+ */
 unsigned long rb_genrand_ulong_limited(unsigned long i);
 
 RBIMPL_SYMBOL_EXPORT_END()