[glib] Move gutils docs inline

[Matthias Clasen <matthiasc src gnome org>]

commit 7648415a5012ee595b07490f818f940e2bea2f7c
Author: Matthias Clasen <mclasen redhat com>
Date:   Wed Jun 8 23:44:39 2011 -0400

    Move gutils docs inline

 docs/reference/glib/tmpl/.gitignore      |    1 +
 docs/reference/glib/tmpl/misc_utils.sgml |  458 ------------------------------
 glib/gprimes.c                           |   20 +-
 glib/gtypes.h                            |    9 +
 glib/gutils.c                            |   59 ++++
 glib/gutils.h                            |   27 ++-
 6 files changed, 102 insertions(+), 472 deletions(-)
---
diff --git a/docs/reference/glib/tmpl/.gitignore b/docs/reference/glib/tmpl/.gitignore
index 513daf2..2c7fc71 100644
--- a/docs/reference/glib/tmpl/.gitignore
+++ b/docs/reference/glib/tmpl/.gitignore
@@ -24,6 +24,7 @@ linked_lists_single.sgml
 markup.sgml
 memory_chunks.sgml
 memory.sgml
+misc_utils.sgml
 option.sgml
 patterns.sgml
 quarks.sgml
diff --git a/glib/gprimes.c b/glib/gprimes.c
index 6698c56..6e27343 100644
--- a/glib/gprimes.c
+++ b/glib/gprimes.c
@@ -71,16 +71,28 @@ static const guint g_primes[] =
   13845163,
 };
 
-static const guint g_nprimes = sizeof (g_primes) / sizeof (g_primes[0]);
-
+/**
+ * g_spaced_primes_closest:
+ * @num: a #guint
+ *
+ * Gets the smallest prime number from a built-in array of primes which
+ * is larger than @num. This is used within GLib to calculate the optimum
+ * size of a #GHashTable.
+ *
+ * The built-in array of primes ranges from 11 to 13845163 such that
+ * each prime is approximately 1.5-2 times the previous prime.
+ *
+ * Returns: the smallest prime number from a built-in array of primes
+ *     which is larger than @num
+ */
 guint
 g_spaced_primes_closest (guint num)
 {
   gint i;
 
-  for (i = 0; i < g_nprimes; i++)
+  for (i = 0; i < G_N_ELEMENTS (g_primes); i++)
     if (g_primes[i] > num)
       return g_primes[i];
 
-  return g_primes[g_nprimes - 1];
+  return g_primes[G_N_ELEMENTS (g_primes) - 1];
 }
diff --git a/glib/gtypes.h b/glib/gtypes.h
index 966f731..8e77563 100644
--- a/glib/gtypes.h
+++ b/glib/gtypes.h
@@ -92,6 +92,15 @@ typedef guint           (*GHashFunc)            (gconstpointer  key);
 typedef void            (*GHFunc)               (gpointer       key,
                                                  gpointer       value,
                                                  gpointer       user_data);
+
+/**
+ * GFreeFunc:
+ * @data: a data pointer
+ *
+ * Declares a type of function which takes an arbitrary
+ * data pointer argument and has no return value. It is
+ * not currently used in GLib or GTK+.
+ */
 typedef void            (*GFreeFunc)            (gpointer       data);
 
 /**
diff --git a/glib/gutils.c b/glib/gutils.c
index 604d8c2..cb08926 100644
--- a/glib/gutils.c
+++ b/glib/gutils.c
@@ -77,6 +77,15 @@
 #include "gwin32.h"
 #endif
 
+
+/**
+ * SECTION:misc_utils
+ * @title: Miscellaneous Utility Functions
+ * @short_description: a selection of portable utility functions
+ *
+ * These are portable utility functions.
+ */
+
 #ifdef	MAXPATHLEN
 #define	G_PATH_LENGTH	MAXPATHLEN
 #elif	defined (PATH_MAX)
@@ -915,6 +924,56 @@ g_path_skip_root (const gchar *file_name)
 }
 
 /**
+ * g_bit_nth_lsf:
+ * @mask: a #gulong containing flags
+ * @nth_bit: the index of the bit to start the search from
+ *
+ * Find the position of the first bit set in @mask, searching
+ * from (but not including) @nth_bit upwards. Bits are numbered
+ * from 0 (least significant) to sizeof(#gulong) * 8 - 1 (31 or 63,
+ * usually). To start searching from the 0th bit, set @nth_bit to -1.
+ *
+ * Returns: the index of the first bit set which is higher than @nth_bit
+ */
+
+/**
+ * g_bit_nth_msf:
+ * @mask: a #gulong containing flags
+ * @nth_bit: the index of the bit to start the search from
+ *
+ * Find the position of the first bit set in @mask, searching
+ * from (but not including) @nth_bit downwards. Bits are numbered
+ * from 0 (least significant) to sizeof(#gulong) * 8 - 1 (31 or 63,
+ * usually). To start searching from the last bit, set @nth_bit to
+ * -1 or GLIB_SIZEOF_LONG * 8.
+ *
+ * Returns: the index of the first bit set which is lower than @nth_bit
+ */
+
+/**
+ * g_bit_storage:
+ * @number: a #guint
+ *
+ * Gets the number of bits used to hold @number,
+ * e.g. if @number is 4, 3 bits are needed.
+ *
+ * Returns: the number of bits used to hold @number
+ */
+
+/**
+ * g_dirname:
+ * @file_name: the name of the file
+ *
+ * Gets the directory components of a file name.
+ * If the file name has no directory components "." is returned.
+ * The returned string should be freed when no longer needed.
+ *
+ * Returns: the directory components of the file
+ *
+ * Deprecated: use g_path_get_dirname() instead
+ */
+
+/**
  * g_path_get_dirname:
  * @file_name: the name of the file.
  *
diff --git a/glib/gutils.h b/glib/gutils.h
index cfb745f..edf9c3c 100644
--- a/glib/gutils.h
+++ b/glib/gutils.h
@@ -196,7 +196,15 @@ typedef enum {
 
 G_CONST_RETURN gchar* g_get_user_special_dir (GUserDirectory directory);
 
-typedef struct _GDebugKey	GDebugKey;
+/**
+ * GDebugKey:
+ * @key: the string
+ * @value: the flag
+ *
+ * Associates a string with a bit flag.
+ * Used in g_parse_debug_string().
+ */
+typedef struct _GDebugKey GDebugKey;
 struct _GDebugKey
 {
   const gchar *key;
@@ -226,10 +234,6 @@ G_CONST_RETURN gchar* g_path_skip_root     (const gchar *file_name);
 
 #ifndef G_DISABLE_DEPRECATED
 
-/* These two functions are deprecated and will be removed in the next
- * major release of GLib. Use g_path_get_dirname/g_path_get_basename
- * instead. Whatch out! The string returned by g_path_get_basename
- * must be g_freed, while the string returned by g_basename must not.*/
 G_CONST_RETURN gchar* g_basename           (const gchar *file_name);
 #define g_dirname g_path_get_dirname
 
@@ -272,13 +276,16 @@ gchar**               g_get_environ        (void);
 const gchar*	     _g_getenv_nomalloc	   (const gchar	*variable,
 					    gchar        buffer[1024]);
 
-/* we try to provide a useful equivalent for ATEXIT if it is
- * not defined, but use is actually abandoned. people should
- * use g_atexit() instead.
+/**
+ * GVoidFunc:
+ *
+ * Declares a type of function which takes no arguments
+ * and has no return value. It is used to specify the type
+ * function passed to g_atexit().
  */
-typedef	void		(*GVoidFunc)		(void);
+typedef void (*GVoidFunc) (void);
 #ifndef ATEXIT
-# define ATEXIT(proc)	g_ATEXIT(proc)
+# define ATEXIT(proc) g_ATEXIT(proc)
 #else
 # define G_NATIVE_ATEXIT
 #endif /* ATEXIT */