Added inline documentation.

2000-10-13  Sebastian Wilhelmi  <wilhelmi@ira.uka.de>

	* grand.c: Added inline documentation.

	* docs/refernce/glib/glib-sections.txt: Added misc items.

	* docs/refernce/glib/tmpl/random_numbers.sgml: Documentation for
        the random number generator.

ChangeLog

@@ -1,5 +1,7 @@
 2000-10-13  Sebastian Wilhelmi  <wilhelmi@ira.uka.de>
 
+	* grand.c: Added inline documentation. 
+
 	* gtypes.h, gnode.h, gutils.h: Readded GFreeFunc,
 	g_node_insert_after and g_find_program_in_path resp., which
 	mysteriously disappeared during the glib.h dissection.

ChangeLog.pre-2-0

@@ -1,5 +1,7 @@
 2000-10-13  Sebastian Wilhelmi  <wilhelmi@ira.uka.de>
 
+	* grand.c: Added inline documentation. 
+
 	* gtypes.h, gnode.h, gutils.h: Readded GFreeFunc,
 	g_node_insert_after and g_find_program_in_path resp., which
 	mysteriously disappeared during the glib.h dissection.

ChangeLog.pre-2-10

@@ -1,5 +1,7 @@
 2000-10-13  Sebastian Wilhelmi  <wilhelmi@ira.uka.de>
 
+	* grand.c: Added inline documentation. 
+
 	* gtypes.h, gnode.h, gutils.h: Readded GFreeFunc,
 	g_node_insert_after and g_find_program_in_path resp., which
 	mysteriously disappeared during the glib.h dissection.

ChangeLog.pre-2-12

@@ -1,5 +1,7 @@
 2000-10-13  Sebastian Wilhelmi  <wilhelmi@ira.uka.de>
 
+	* grand.c: Added inline documentation. 
+
 	* gtypes.h, gnode.h, gutils.h: Readded GFreeFunc,
 	g_node_insert_after and g_find_program_in_path resp., which
 	mysteriously disappeared during the glib.h dissection.

ChangeLog.pre-2-2

@@ -1,5 +1,7 @@
 2000-10-13  Sebastian Wilhelmi  <wilhelmi@ira.uka.de>
 
+	* grand.c: Added inline documentation. 
+
 	* gtypes.h, gnode.h, gutils.h: Readded GFreeFunc,
 	g_node_insert_after and g_find_program_in_path resp., which
 	mysteriously disappeared during the glib.h dissection.

ChangeLog.pre-2-4

@@ -1,5 +1,7 @@
 2000-10-13  Sebastian Wilhelmi  <wilhelmi@ira.uka.de>
 
+	* grand.c: Added inline documentation. 
+
 	* gtypes.h, gnode.h, gutils.h: Readded GFreeFunc,
 	g_node_insert_after and g_find_program_in_path resp., which
 	mysteriously disappeared during the glib.h dissection.

ChangeLog.pre-2-6

@@ -1,5 +1,7 @@
 2000-10-13  Sebastian Wilhelmi  <wilhelmi@ira.uka.de>
 
+	* grand.c: Added inline documentation. 
+
 	* gtypes.h, gnode.h, gutils.h: Readded GFreeFunc,
 	g_node_insert_after and g_find_program_in_path resp., which
 	mysteriously disappeared during the glib.h dissection.

ChangeLog.pre-2-8

@@ -1,5 +1,7 @@
 2000-10-13  Sebastian Wilhelmi  <wilhelmi@ira.uka.de>
 
+	* grand.c: Added inline documentation. 
+
 	* gtypes.h, gnode.h, gutils.h: Readded GFreeFunc,
 	g_node_insert_after and g_find_program_in_path resp., which
 	mysteriously disappeared during the glib.h dissection.

docs/reference/ChangeLog

@@ -1,3 +1,10 @@
+2000-10-13  Sebastian Wilhelmi  <wilhelmi@ira.uka.de>
+
+	* glib/glib-sections.txt: Added misc items.
+
+	* glib/tmpl/random_numbers.sgml: Documentation for the random
+	number generator.
+
 2000-10-09  Raja R Harinath  <harinath@cs.umn.edu>
 
 	* gobject/Makefile.am (DOC_SOURCE_DIR): Don't set to 

docs/reference/glib/glib-sections.txt

@@ -255,6 +255,10 @@ G_INLINE_FUNC
 G_STMT_START
 G_STMT_END
 
+<SUBSECTION>
+G_BEGIN_DECLS
+G_END_DECLS
+
 <SUBSECTION>
 G_N_ELEMENTS
 
@@ -269,6 +273,7 @@ G_GNUC_EXTENSION
 G_GNUC_CONST
 G_GNUC_NORETURN
 G_GNUC_UNUSED
+G_GNUC_PURE
 G_GNUC_PRINTF
 G_GNUC_SCANF
 G_GNUC_FORMAT
@@ -359,6 +364,8 @@ g_source_remove_by_user_data
 
 <SUBSECTION Private>
 GLIB_HAVE_SYS_POLL_H
+GLIB_HAVE_ALLOCA_H
+alloca
 GLIB_SYSDEF_POLLERR
 GLIB_SYSDEF_POLLHUP
 GLIB_SYSDEF_POLLIN
@@ -466,9 +473,15 @@ g_static_private_set
 g_static_private_set_for_thread
 
 <SUBSECTION Private>
+G_THREAD_ECF
 G_THREAD_CF
 G_THREAD_UF
 g_static_mutex_get_mutex_impl
+g_mutex_lock_with_debug_name
+g_mutex_trylock_with_debug_name
+g_mutex_unlock_with_debug_name
+G_MUTEX_DEBUG_MAGIC
+g_thread_init_with_errorcheck_mutexes
 G_LOCK_NAME
 glib_dummy_decl
 GSystemThread
@@ -575,6 +588,9 @@ g_realloc
 <SUBSECTION>
 g_free
 
+<SUBSECTION>
+g_alloca
+
 <SUBSECTION>
 g_memmove
 g_memdup

docs/reference/glib/tmpl/random_numbers.sgml

@@ -2,139 +2,60 @@
 Random Numbers
 
 <!-- ##### SECTION Short_Description ##### -->
-
+pseudo random number generator.
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>
-
+The following functions allow you to use a portable, fast and good
+pseudo random number generator (PRNG). It uses the Mersenne Twister
+PRNG, which was originally developed by Makoto Matsumoto and Takuji
+Nishimura. Further information can be found at <ulink
+url="http://www.math.keio.ac.jp/~matumoto/emt.html"
+>www.math.keio.ac.jp/~matumoto/emt.html</ulink>.
 </para>
 
-<!-- ##### SECTION See_Also ##### -->
 <para>
+If you just need a random number, you simply call the g_random_*
+functions, which will create a globally used #GRand and use the
+according g_rand_* function internally. Whenever you need a stream of
+reproducible random numbers, you better create a #GRand yourself and
+use the g_rand_* functions directly, which will also be slightly
+faster. Initializing a GRand with a certain seed will produce exactly
+the same series of random numbers on all platforms. This can thus be
+used as a seed for e.g. games.
+</para>
 
+<para>
+The g_rand*_range functions will return high quality equally
+distributed random numbers, whereas for example the
+<literal>(g_random_int()%%max)</literal> approach often doesn't
+yield equally distributed numbers.
+</para>
+
+<para>
+A random binary decision is best implemented by using
+<literal>if(g_random_int()&amp;(1<<@a))</literal>, where @a can be every
+integer constant from 0 to 31. The Mersenne Twister PRNG is said to
+produce highly random lower bits too, but it is common not to rely on
+that, so choosing @a to be from 4 to 31 might be wise.
 </para>
 
 <!-- ##### STRUCT GRand ##### -->
 <para>
-
+The #GRand struct is an opaque data structure. It should only be
+accessed through the g_rand_* functions.
 </para>
 
-
 <!-- ##### FUNCTION g_rand_new_with_seed ##### -->
-<para>
-
-</para>
-
-@seed: 
-@Returns: 
-
-
 <!-- ##### FUNCTION g_rand_new ##### -->
-<para>
-
-</para>
-
-@Returns: 
-
-
 <!-- ##### FUNCTION g_rand_free ##### -->
-<para>
-
-</para>
-
-@rand: 
-
-
 <!-- ##### FUNCTION g_rand_set_seed ##### -->
-<para>
-
-</para>
-
-@rand: 
-@seed: 
-
-
 <!-- ##### FUNCTION g_rand_int ##### -->
-<para>
-
-</para>
-
-@rand: 
-@Returns: 
-
-
 <!-- ##### FUNCTION g_rand_int_range ##### -->
-<para>
-
-</para>
-
-@rand: 
-@min: 
-@max: 
-@Returns: 
-
-
 <!-- ##### FUNCTION g_rand_double ##### -->
-<para>
-
-</para>
-
-@rand: 
-@Returns: 
-
-
 <!-- ##### FUNCTION g_rand_double_range ##### -->
-<para>
-
-</para>
-
-@rand: 
-@min: 
-@max: 
-@Returns: 
-
-
 <!-- ##### FUNCTION g_random_set_seed ##### -->
-<para>
-
-</para>
-
-@seed: 
-
-
 <!-- ##### FUNCTION g_random_int ##### -->
-<para>
-
-</para>
-
-@Returns: 
-
-
 <!-- ##### FUNCTION g_random_int_range ##### -->
-<para>
-
-</para>
-
-@min: 
-@max: 
-@Returns: 
-
-
 <!-- ##### FUNCTION g_random_double ##### -->
-<para>
-
-</para>
-
-@Returns: 
-
-
 <!-- ##### FUNCTION g_random_double_range ##### -->
-<para>
-
-</para>
-
-@min: 
-@max: 
-@Returns: 
-
-

glib/grand.c

@@ -64,6 +64,14 @@ struct _GRand
   guint mti; 
 };
 
+/**
+ * g_rand_new_with_seed:
+ * @seed: a value to initialize the random number generator.
+ * 
+ * Creates a new random number generator initialized with @seed.
+ * 
+ * Return value: the new #GRand.
+ **/
 GRand*
 g_rand_new_with_seed (guint32 seed)
 {
@@ -72,6 +80,15 @@ g_rand_new_with_seed (guint32 seed)
   return rand;
 }
 
+/**
+ * g_rand_new:
+ * 
+ * Creates a new random number generator initialized with a seed taken
+ * either from /dev/urandom (if existing) or from the current time (as
+ * a fallback).
+ * 
+ * Return value: the new #GRand.
+ **/
 GRand* 
 g_rand_new (void)
 {
@@ -100,6 +117,12 @@ g_rand_new (void)
   return g_rand_new_with_seed (seed);
 }
 
+/**
+ * g_rand_free:
+ * @rand: a #GRand.
+ *
+ * Frees the memory allocated for the #GRand.
+ **/
 void
 g_rand_free (GRand* rand)
 {
@@ -108,6 +131,13 @@ g_rand_free (GRand* rand)
   g_free (rand);
 }
 
+/**
+ * g_rand_set_seed:
+ * @rand: a #GRand.
+ * @seed: a value to reinitialize the random number generator.
+ *
+ * Sets the seed for the random number generator #GRand to @seed.
+ **/
 void
 g_rand_set_seed (GRand* rand, guint32 seed)
 {
@@ -126,6 +156,15 @@ g_rand_set_seed (GRand* rand, guint32 seed)
     rand->mt[rand->mti] = (69069 * rand->mt[rand->mti-1]) & 0xffffffff;
 }
 
+/**
+ * g_rand_int:
+ * @rand: a #GRand.
+ *
+ * Return the next random #guint32 from @rand equaly distributed over
+ * the range [0..2^32-1].
+ *
+ * Return value: A random number.
+ **/
 guint32
 g_rand_int (GRand* rand)
 {
@@ -161,6 +200,17 @@ g_rand_int (GRand* rand)
   return y; 
 }
 
+/**
+ * g_rand_int_range:
+ * @rand: a #GRand.
+ * @min: lower closed bound of the interval.
+ * @max: upper open bound of the interval.
+ *
+ * Return the next random #gint32 from @rand equaly distributed over
+ * the range [@min..@max-1].
+ *
+ * Return value: A random number.
+ **/
 gint32 
 g_rand_int_range (GRand* rand, gint32 min, gint32 max)
 {
@@ -215,18 +265,46 @@ g_rand_int_range (GRand* rand, gint32 min, gint32 max)
 /* transform [0..2^32-1] -> [0..1) */
 #define G_RAND_DOUBLE_TRANSFORM 2.3283064365386963e-10
 
+/**
+ * g_rand_double:
+ * @rand: a #GRand.
+ *
+ * Return the next random #gdouble from @rand equaly distributed over
+ * the range [0..1).
+ *
+ * Return value: A random number.
+ **/
 gdouble 
 g_rand_double (GRand* rand)
 {                            
   return g_rand_int (rand) * G_RAND_DOUBLE_TRANSFORM;
 }
 
+/**
+ * g_rand_double_range:
+ * @rand: a #GRand.
+ * @min: lower closed bound of the interval.
+ * @max: upper open bound of the interval.
+ *
+ * Return the next random #gdouble from @rand equaly distributed over
+ * the range [@min..@max).
+ *
+ * Return value: A random number.
+ **/
 gdouble 
 g_rand_double_range (GRand* rand, gdouble min, gdouble max)
 {
   return g_rand_int (rand) * ((max - min) * G_RAND_DOUBLE_TRANSFORM)  + min;
 }
 
+/**
+ * g_random_int:
+ *
+ * Return a random #guint32 equaly distributed over the range
+ * [0..2^32-1].
+ *
+ * Return value: A random number.
+ **/
 guint32
 g_random_int (void)
 {
@@ -240,6 +318,16 @@ g_random_int (void)
   return result;
 }
 
+/**
+ * g_random_int_range:
+ * @min: lower closed bound of the interval.
+ * @max: upper open bound of the interval.
+ *
+ * Return a random #gint32 equaly distributed over the range
+ * [@min..@max-1].
+ *
+ * Return value: A random number.
+ **/
 gint32 
 g_random_int_range (gint32 min, gint32 max)
 {
@@ -253,6 +341,13 @@ g_random_int_range (gint32 min, gint32 max)
   return result;
 }
 
+/**
+ * g_random_double:
+ *
+ * Return a random #gdouble equaly distributed over the range [0..1).
+ *
+ * Return value: A random number.
+ **/
 gdouble 
 g_random_double (void)
 {
@@ -266,6 +361,15 @@ g_random_double (void)
   return result;
 }
 
+/**
+ * g_random_double_range:
+ * @min: lower closed bound of the interval.
+ * @max: upper open bound of the interval.
+ *
+ * Return a random #gdouble equaly distributed over the range [@min..@max).
+ *
+ * Return value: A random number.
+ **/
 gdouble 
 g_random_double_range (gdouble min, gdouble max)
 {
@@ -279,6 +383,13 @@ g_random_double_range (gdouble min, gdouble max)
   return result;
 }
 
+/**
+ * g_random_set_seed:
+ * @seed: a value to reinitialize the global random number generator.
+ * 
+ * Sets the seed for the global random number generator, which is used
+ * by te g_random_* functions, to @seed.
+ **/
 void
 g_random_set_seed (guint32 seed)
 {

grand.c

@@ -64,6 +64,14 @@ struct _GRand
   guint mti; 
 };
 
+/**
+ * g_rand_new_with_seed:
+ * @seed: a value to initialize the random number generator.
+ * 
+ * Creates a new random number generator initialized with @seed.
+ * 
+ * Return value: the new #GRand.
+ **/
 GRand*
 g_rand_new_with_seed (guint32 seed)
 {
@@ -72,6 +80,15 @@ g_rand_new_with_seed (guint32 seed)
   return rand;
 }
 
+/**
+ * g_rand_new:
+ * 
+ * Creates a new random number generator initialized with a seed taken
+ * either from /dev/urandom (if existing) or from the current time (as
+ * a fallback).
+ * 
+ * Return value: the new #GRand.
+ **/
 GRand* 
 g_rand_new (void)
 {
@@ -100,6 +117,12 @@ g_rand_new (void)
   return g_rand_new_with_seed (seed);
 }
 
+/**
+ * g_rand_free:
+ * @rand: a #GRand.
+ *
+ * Frees the memory allocated for the #GRand.
+ **/
 void
 g_rand_free (GRand* rand)
 {
@@ -108,6 +131,13 @@ g_rand_free (GRand* rand)
   g_free (rand);
 }
 
+/**
+ * g_rand_set_seed:
+ * @rand: a #GRand.
+ * @seed: a value to reinitialize the random number generator.
+ *
+ * Sets the seed for the random number generator #GRand to @seed.
+ **/
 void
 g_rand_set_seed (GRand* rand, guint32 seed)
 {
@@ -126,6 +156,15 @@ g_rand_set_seed (GRand* rand, guint32 seed)
     rand->mt[rand->mti] = (69069 * rand->mt[rand->mti-1]) & 0xffffffff;
 }
 
+/**
+ * g_rand_int:
+ * @rand: a #GRand.
+ *
+ * Return the next random #guint32 from @rand equaly distributed over
+ * the range [0..2^32-1].
+ *
+ * Return value: A random number.
+ **/
 guint32
 g_rand_int (GRand* rand)
 {
@@ -161,6 +200,17 @@ g_rand_int (GRand* rand)
   return y; 
 }
 
+/**
+ * g_rand_int_range:
+ * @rand: a #GRand.
+ * @min: lower closed bound of the interval.
+ * @max: upper open bound of the interval.
+ *
+ * Return the next random #gint32 from @rand equaly distributed over
+ * the range [@min..@max-1].
+ *
+ * Return value: A random number.
+ **/
 gint32 
 g_rand_int_range (GRand* rand, gint32 min, gint32 max)
 {
@@ -215,18 +265,46 @@ g_rand_int_range (GRand* rand, gint32 min, gint32 max)
 /* transform [0..2^32-1] -> [0..1) */
 #define G_RAND_DOUBLE_TRANSFORM 2.3283064365386963e-10
 
+/**
+ * g_rand_double:
+ * @rand: a #GRand.
+ *
+ * Return the next random #gdouble from @rand equaly distributed over
+ * the range [0..1).
+ *
+ * Return value: A random number.
+ **/
 gdouble 
 g_rand_double (GRand* rand)
 {                            
   return g_rand_int (rand) * G_RAND_DOUBLE_TRANSFORM;
 }
 
+/**
+ * g_rand_double_range:
+ * @rand: a #GRand.
+ * @min: lower closed bound of the interval.
+ * @max: upper open bound of the interval.
+ *
+ * Return the next random #gdouble from @rand equaly distributed over
+ * the range [@min..@max).
+ *
+ * Return value: A random number.
+ **/
 gdouble 
 g_rand_double_range (GRand* rand, gdouble min, gdouble max)
 {
   return g_rand_int (rand) * ((max - min) * G_RAND_DOUBLE_TRANSFORM)  + min;
 }
 
+/**
+ * g_random_int:
+ *
+ * Return a random #guint32 equaly distributed over the range
+ * [0..2^32-1].
+ *
+ * Return value: A random number.
+ **/
 guint32
 g_random_int (void)
 {
@@ -240,6 +318,16 @@ g_random_int (void)
   return result;
 }
 
+/**
+ * g_random_int_range:
+ * @min: lower closed bound of the interval.
+ * @max: upper open bound of the interval.
+ *
+ * Return a random #gint32 equaly distributed over the range
+ * [@min..@max-1].
+ *
+ * Return value: A random number.
+ **/
 gint32 
 g_random_int_range (gint32 min, gint32 max)
 {
@@ -253,6 +341,13 @@ g_random_int_range (gint32 min, gint32 max)
   return result;
 }
 
+/**
+ * g_random_double:
+ *
+ * Return a random #gdouble equaly distributed over the range [0..1).
+ *
+ * Return value: A random number.
+ **/
 gdouble 
 g_random_double (void)
 {
@@ -266,6 +361,15 @@ g_random_double (void)
   return result;
 }
 
+/**
+ * g_random_double_range:
+ * @min: lower closed bound of the interval.
+ * @max: upper open bound of the interval.
+ *
+ * Return a random #gdouble equaly distributed over the range [@min..@max).
+ *
+ * Return value: A random number.
+ **/
 gdouble 
 g_random_double_range (gdouble min, gdouble max)
 {
@@ -279,6 +383,13 @@ g_random_double_range (gdouble min, gdouble max)
   return result;
 }
 
+/**
+ * g_random_set_seed:
+ * @seed: a value to reinitialize the global random number generator.
+ * 
+ * Sets the seed for the global random number generator, which is used
+ * by te g_random_* functions, to @seed.
+ **/
 void
 g_random_set_seed (guint32 seed)
 {