[PATCHES] glib/gmem: programmatic access to profiling data and gtk-doc migration

[Jon Nordby <jonn openismus com>]

01 solves https://bugzilla.gnome.org/show_bug.cgi?id=523260 so I've
attached the patch there too.

Sorry for not inlining, my email client tends to mess it up.


>From 040a2451cddb6329686ce9945dd352ea19823510 Mon Sep 17 00:00:00 2001
From: Jon Nordby <jonn openismus com>
Date: Thu, 26 Aug 2010 09:31:27 +0200
Subject: [PATCH 1/2] gmem: Add programmatic access to profiling data

Bug 523260.
---
 docs/reference/glib/glib-sections.txt |    3 +
 glib/glib.symbols                     |    3 +
 glib/gmem.c                           |   90 +++++++++++++++++++++++++++++++++
 glib/gmem.h                           |    4 +-
 4 files changed, 99 insertions(+), 1 deletions(-)

diff --git a/docs/reference/glib/glib-sections.txt b/docs/reference/glib/glib-sections.txt
index 3fa1d2f..9be0453 100644
--- a/docs/reference/glib/glib-sections.txt
+++ b/docs/reference/glib/glib-sections.txt
@@ -896,6 +896,9 @@ g_mem_is_system_malloc
 <SUBSECTION>
 glib_mem_profiler_table
 g_mem_profile
+g_mem_profile_bytes_allocated
+g_mem_profile_bytes_freed
+g_mem_profile_bytes_zeroinited
 </SECTION>
 
 <SECTION>
diff --git a/glib/glib.symbols b/glib/glib.symbols
index 41e133a..846bef5 100644
--- a/glib/glib.symbols
+++ b/glib/glib.symbols
@@ -780,6 +780,9 @@ g_malloc_n G_GNUC_MALLOC
 g_malloc0_n G_GNUC_MALLOC
 g_mem_is_system_malloc
 g_mem_profile
+g_mem_profile_bytes_allocated
+g_mem_profile_bytes_freed
+g_mem_profile_bytes_zeroinited
 g_mem_set_vtable
 g_realloc
 g_realloc_n
diff --git a/glib/gmem.c b/glib/gmem.c
index 2c9b74a..20c76dc 100644
--- a/glib/gmem.c
+++ b/glib/gmem.c
@@ -411,6 +411,21 @@ void
 g_mem_profile (void)
 {
 }
+gsize
+g_mem_profile_bytes_allocated (void)
+{
+  return 0;
+}
+gsize
+g_mem_profile_bytes_freed (void)
+{
+  return 0;
+}
+gsize
+g_mem_profile_bytes_zeroinited (void)
+{
+  return 0;
+}
 #else	/* !G_DISABLE_CHECKS */
 typedef enum {
   PROFILER_FREE		= 0,
@@ -550,6 +565,81 @@ g_mem_profile (void)
 	   local_allocs - local_frees);
 }
 
+/**
+ * g_mem_profile_bytes_allocated:
+ *
+ * Note that this function always return zero unless you have
+ *   previously installed the #glib_mem_profiler_table with g_mem_set_vtable().
+ *
+ * Return value: The total number of bytes that has been allocated
+ *
+ * Since: 2.26
+ */
+gsize
+g_mem_profile_bytes_allocated (void)
+{
+  gsize local_allocs;
+
+  if (G_UNLIKELY (!g_mem_initialized))
+    g_mem_init_nomessage();
+
+  g_mutex_lock (gmem_profile_mutex);
+  local_allocs = profile_allocs;
+  g_mutex_unlock (gmem_profile_mutex);
+
+  return local_allocs;
+}
+
+/**
+ * g_mem_profile_bytes_freed:
+ *
+ * Note that this function always return zero unless you have
+ *   previously installed the #glib_mem_profiler_table with g_mem_set_vtable().
+ *
+ * Return value: The total number of bytes that has been freed
+ *
+ * Since: 2.26
+ */
+gsize
+g_mem_profile_bytes_freed (void)
+{
+  gsize local_frees;
+
+  if (G_UNLIKELY (!g_mem_initialized))
+    g_mem_init_nomessage();
+
+  g_mutex_lock (gmem_profile_mutex);
+  local_frees = profile_frees;
+  g_mutex_unlock (gmem_profile_mutex);
+
+  return local_frees;
+}
+
+/**
+ * g_mem_profile_bytes_zeroinited:
+ *
+ * Note that this function always return zero unless you have
+ *   previously installed the #glib_mem_profiler_table with g_mem_set_vtable().
+ *
+ * Return value: The total number of bytes that has been zero initialized
+ *
+ * Since: 2.26
+ */
+gsize
+g_mem_profile_bytes_zeroinited (void)
+{
+  gsize local_zinit;
+
+  if (G_UNLIKELY (!g_mem_initialized))
+    g_mem_init_nomessage();
+
+  g_mutex_lock (gmem_profile_mutex);
+  local_zinit = profile_zinit;
+  g_mutex_unlock (gmem_profile_mutex);
+
+  return local_zinit;
+}
+
 static gpointer
 profiler_try_malloc (gsize n_bytes)
 {
diff --git a/glib/gmem.h b/glib/gmem.h
index d005eb1..a28ee7c 100644
--- a/glib/gmem.h
+++ b/glib/gmem.h
@@ -153,7 +153,9 @@ GLIB_VAR gboolean g_mem_gc_friendly;
  */
 GLIB_VAR GMemVTable	*glib_mem_profiler_table;
 void	g_mem_profile	(void);
-
+gsize g_mem_profile_bytes_allocated (void);
+gsize g_mem_profile_bytes_freed (void);
+gsize g_mem_profile_bytes_zeroinited (void);
 
 /* deprecated memchunks and allocators */
 #if !defined (G_DISABLE_DEPRECATED) || defined (GTK_COMPILATION) || defined (GDK_COMPILATION)
-- 
1.7.2.1

>From eb0aa61d290a0c05b0801c3a155a94bec25fcca3 Mon Sep 17 00:00:00 2001
From: Jon Nordby <jonn openismus com>
Date: Thu, 26 Aug 2010 16:51:33 +0200
Subject: [PATCH 2/2] docs: Inline docs from tmpl/memory.smgl

---
 docs/reference/glib/tmpl/.gitignore  |    1 +
 docs/reference/glib/tmpl/memory.sgml |  428 ----------------------------------
 glib/galloca.h                       |   47 ++++
 glib/gmem.c                          |  201 ++++++++++++++++-
 glib/gmem.h                          |  106 +++++++++
 glib/gstrfuncs.c                     |   11 +
 6 files changed, 365 insertions(+), 429 deletions(-)
 delete mode 100644 docs/reference/glib/tmpl/memory.sgml

diff --git a/docs/reference/glib/tmpl/.gitignore b/docs/reference/glib/tmpl/.gitignore
index 17cf581..606dd26 100644
--- a/docs/reference/glib/tmpl/.gitignore
+++ b/docs/reference/glib/tmpl/.gitignore
@@ -17,6 +17,7 @@ iochannels.sgml
 linked_lists_double.sgml
 linked_lists_single.sgml
 memory_chunks.sgml
+memory.sgml
 option.sgml
 patterns.sgml
 quarks.sgml
diff --git a/docs/reference/glib/tmpl/memory.sgml b/docs/reference/glib/tmpl/memory.sgml
deleted file mode 100644
index 3e8fe97..0000000
--- a/docs/reference/glib/tmpl/memory.sgml
+++ /dev/null
@@ -1,428 +0,0 @@
-<!-- ##### SECTION Title ##### -->
-Memory Allocation
-
-<!-- ##### SECTION Short_Description ##### -->
-general memory-handling
-
-<!-- ##### SECTION Long_Description ##### -->
-<para>
-These functions provide support for allocating and freeing memory.
-</para>
-
-<note>
-<para>
-If any call to allocate memory fails, the application is terminated.
-This also means that there is no need to check if the call succeeded.
-</para>
-</note>
-
-<note>
-<para>
-It's important to match g_malloc() with g_free(), plain malloc() with free(),
-and (if you're using C++) new with delete and new[] with delete[]. Otherwise
-bad things can happen, since these allocators may use different memory
-pools (and new/delete call constructors and destructors). See also
-g_mem_set_vtable().
-</para>
-</note>
-
-<!-- ##### SECTION See_Also ##### -->
-<para>
-
-</para>
-
-<!-- ##### SECTION Stability_Level ##### -->
-
-
-<!-- ##### SECTION Image ##### -->
-
-
-<!-- ##### MACRO g_new ##### -->
-<para>
-Allocates @n_structs elements of type @struct_type.
-The returned pointer is cast to a pointer to the given type.
-If @n_structs is 0 it returns %NULL.
-Care is taken to avoid overflow when calculating the size of the allocated block.
-</para>
-<para>
-Since the returned pointer is already casted to the right type,
-it is normally unnecessary to cast it explicitly, and doing
-so might hide memory allocation errors.
-</para>
-
- struct_type: the type of the elements to allocate
- n_structs: the number of elements to allocate
- Returns: a pointer to the allocated memory, cast to a pointer to @struct_type
-
-
-<!-- ##### MACRO g_new0 ##### -->
-<para>
-Allocates @n_structs elements of type @struct_type, initialized to 0's.
-The returned pointer is cast to a pointer to the given type.
-If @n_structs is 0 it returns %NULL.
-Care is taken to avoid overflow when calculating the size of the allocated block.
-</para>
-<para>
-Since the returned pointer is already casted to the right type,
-it is normally unnecessary to cast it explicitly, and doing
-so might hide memory allocation errors.
-</para>
-
- struct_type: the type of the elements to allocate.
- n_structs: the number of elements to allocate.
- Returns: a pointer to the allocated memory, cast to a pointer to @struct_type.
-
-
-<!-- ##### MACRO g_renew ##### -->
-<para>
-Reallocates the memory pointed to by @mem, so that it now has space for
- n_structs elements of type @struct_type. It returns the new address of 
-the memory, which may have been moved.
-Care is taken to avoid overflow when calculating the size of the allocated block.
-</para>
-
- struct_type: the type of the elements to allocate
- mem: the currently allocated memory
- n_structs: the number of elements to allocate
- Returns: a pointer to the new allocated memory, cast to a pointer to @struct_type
-
-
-<!-- ##### MACRO g_try_new ##### -->
-<para>
-Attempts to allocate @n_structs elements of type @struct_type, and returns 
-%NULL on failure. Contrast with g_new(), which aborts the program on failure.
-The returned pointer is cast to a pointer to the given type. 
-The function returns %NULL when @n_structs is 0 of if an overflow occurs.
-</para>
-
- struct_type: the type of the elements to allocate
- n_structs: the number of elements to allocate
- Returns: a pointer to the allocated memory, cast to a pointer to @struct_type
- Since: 2.8
-
-
-<!-- ##### MACRO g_try_new0 ##### -->
-<para>
-Attempts to allocate @n_structs elements of type @struct_type, initialized 
-to 0's, and returns %NULL on failure. Contrast with g_new0(), which aborts 
-the program on failure.
-The returned pointer is cast to a pointer to the given type.
-The function returns %NULL when @n_structs is 0 of if an overflow occurs.
-</para>
-
- struct_type: the type of the elements to allocate
- n_structs: the number of elements to allocate
- Returns: a pointer to the allocated memory, cast to a pointer to @struct_type
- Since: 2.8
-
-
-<!-- ##### MACRO g_try_renew ##### -->
-<para>
-Attempts to reallocate the memory pointed to by @mem, so that it now has 
-space for @n_structs elements of type @struct_type, and returns %NULL on 
-failure. Contrast with g_renew(), which aborts the program on failure.
-It returns the new address of the memory, which may have been moved.
-The function returns %NULL if an overflow occurs.
-</para>
-
- struct_type: the type of the elements to allocate
- mem: the currently allocated memory
- n_structs: the number of elements to allocate
- Returns: a pointer to the new allocated memory, cast to a pointer to @struct_type
- Since: 2.8
-
-
-<!-- ##### FUNCTION g_malloc ##### -->
-<para>
-Allocates @n_bytes bytes of memory.
-If @n_bytes is 0 it returns %NULL.
-</para>
-
- n_bytes: the number of bytes to allocate
- Returns: a pointer to the allocated memory
-
-
-<!-- ##### FUNCTION g_malloc0 ##### -->
-<para>
-Allocates @n_bytes bytes of memory, initialized to 0's.
-If @n_bytes is 0 it returns %NULL.
-</para>
-
- n_bytes: the number of bytes to allocate
- Returns: a pointer to the allocated memory
-
-
-<!-- ##### FUNCTION g_realloc ##### -->
-<para>
-Reallocates the memory pointed to by @mem, so that it now has space for
- n_bytes bytes of memory. It returns the new address of the memory, which may
-have been moved. @mem may be %NULL, in which case it's considered to 
-have zero-length. @n_bytes may be 0, in which case %NULL will be returned
-and @mem will be freed unless it is %NULL.
-</para>
-
- mem: the memory to reallocate
- n_bytes: new size of the memory in bytes
- Returns: the new address of the allocated memory
-
-
-<!-- ##### FUNCTION g_try_malloc ##### -->
-<para>
-Attempts to allocate @n_bytes, and returns %NULL on failure. 
-Contrast with g_malloc(), which aborts the program on failure.
-</para>
-
- n_bytes: number of bytes to allocate.
- Returns: the allocated memory, or %NULL.
-
-
-<!-- ##### FUNCTION g_try_malloc0 ##### -->
-<para>
-Attempts to allocate @n_bytes, initialized to 0's, and returns %NULL on 
-failure. Contrast with g_malloc0(), which aborts the program on failure.
-</para>
-
- n_bytes: number of bytes to allocate
- Returns: the allocated memory, or %NULL
- Since: 2.8
-
-
-<!-- ##### FUNCTION g_try_realloc ##### -->
-<para>
-Attempts to realloc @mem to a new size, @n_bytes, and returns %NULL
-on failure. Contrast with g_realloc(), which aborts the program
-on failure. If @mem is %NULL, behaves the same as g_try_malloc().
-</para>
-
- mem: previously-allocated memory, or %NULL.
- n_bytes: number of bytes to allocate.
- Returns: the allocated memory, or %NULL.
-
-
-<!-- ##### FUNCTION g_malloc_n ##### -->
-<para>
-This function is similar to g_malloc(), allocating (@n_blocks * @n_block_bytes) bytes,
-but care is taken to detect possible overflow during multiplication.
-</para>
-
- n_blocks: the number of blocks to allocate
- n_block_bytes: the size of each block in bytes
- Returns: a pointer to the allocated memory
- Since: 2.24
-
-
-<!-- ##### FUNCTION g_malloc0_n ##### -->
-<para>
-This function is similar to g_malloc0(), allocating (@n_blocks * @n_block_bytes) bytes,
-but care is taken to detect possible overflow during multiplication.
-</para>
-
- n_blocks: the number of blocks to allocate
- n_block_bytes: the size of each block in bytes
- Returns: a pointer to the allocated memory
- Since: 2.24
-
-
-<!-- ##### FUNCTION g_realloc_n ##### -->
-<para>
-This function is similar to g_realloc(), allocating (@n_blocks * @n_block_bytes) bytes,
-but care is taken to detect possible overflow during multiplication.
-</para>
-
- mem: the memory to reallocate
- n_blocks: the number of blocks to allocate
- n_block_bytes: the size of each block in bytes
- Returns: the new address of the allocated memory
- Since: 2.24
-
-
-<!-- ##### FUNCTION g_try_malloc_n ##### -->
-<para>
-This function is similar to g_try_malloc(), allocating (@n_blocks * @n_block_bytes) bytes,
-but care is taken to detect possible overflow during multiplication.
-</para>
-
- n_blocks: the number of blocks to allocate
- n_block_bytes: the size of each block in bytes
- Returns: the allocated memory, or %NULL.
- Since: 2.24
-
-
-<!-- ##### FUNCTION g_try_malloc0_n ##### -->
-<para>
-This function is similar to g_try_malloc0(), allocating (@n_blocks * @n_block_bytes) bytes,
-but care is taken to detect possible overflow during multiplication.
-</para>
-
- n_blocks: the number of blocks to allocate
- n_block_bytes: the size of each block in bytes
- Returns: the allocated memory, or %NULL
- Since: 2.24
-
-
-<!-- ##### FUNCTION g_try_realloc_n ##### -->
-<para>
-This function is similar to g_try_realloc(), allocating (@n_blocks * @n_block_bytes) bytes,
-but care is taken to detect possible overflow during multiplication.
-</para>
-
- mem: previously-allocated memory, or %NULL.
- n_blocks: the number of blocks to allocate
- n_block_bytes: the size of each block in bytes
- Returns: the allocated memory, or %NULL.
- Since: 2.24
-
-
-<!-- ##### FUNCTION g_free ##### -->
-<para>
-Frees the memory pointed to by @mem.
-If @mem is %NULL it simply returns.
-</para>
-
- mem: the memory to free
-
-
-<!-- ##### VARIABLE g_mem_gc_friendly ##### -->
-<para>
-This variable is %TRUE if the <envar>G_DEBUG</envar> environment variable
-includes the key <link linkend="G_DEBUG">gc-friendly</link>.  
-</para>
-
-
-<!-- ##### MACRO g_alloca ##### -->
-<para>
-Allocates @size bytes on the stack; these bytes will be freed when the current
-stack frame is cleaned up. This macro essentially just wraps the alloca() 
-function present on most UNIX variants. 
-Thus it provides the same advantages and pitfalls as alloca():
-<variablelist>
-  <varlistentry><term></term><listitem><para>
-    + alloca() is very fast, as on most systems it's implemented by just adjusting
-    the stack pointer register.
-  </para></listitem></varlistentry>
-  <varlistentry><term></term><listitem><para>
-    + It doesn't cause any memory fragmentation, within its scope, separate alloca()
-    blocks just build up and are released together at function end.
-  </para></listitem></varlistentry>
-  <varlistentry><term></term><listitem><para>
-    - Allocation sizes have to fit into the current stack frame. For instance in a
-      threaded environment on Linux, the per-thread stack size is limited to 2 Megabytes,
-      so be sparse with alloca() uses.
-  </para></listitem></varlistentry>
-  <varlistentry><term></term><listitem><para>
-    - Allocation failure due to insufficient stack space is not indicated with a %NULL
-      return like e.g. with malloc(). Instead, most systems probably handle it the same
-      way as out of stack space situations from infinite function recursion, i.e.
-      with a segmentation fault.
-  </para></listitem></varlistentry>
-  <varlistentry><term></term><listitem><para>
-    - Special care has to be taken when mixing alloca() with GNU C variable sized arrays.
-      Stack space allocated with alloca() in the same scope as a variable sized array
-      will be freed together with the variable sized array upon exit of that scope, and
-      not upon exit of the enclosing function scope.
-  </para></listitem></varlistentry>
-</variablelist>
-
-</para>
-
- size:    number of bytes to allocate.
- Returns: space for @size bytes, allocated on the stack
-
-
-<!-- ##### MACRO g_newa ##### -->
-<para>
-Wraps g_alloca() in a more typesafe manner.
-</para>
-
- struct_type: Type of memory chunks to be allocated
- n_structs:   Number of chunks to be allocated
- Returns:     Pointer to stack space for @n_structs chunks of type @struct_type
-
-
-<!-- ##### MACRO g_memmove ##### -->
-<para>
-
-</para>
-
- dest: 
- src: 
- len: 
-
-
-<!-- ##### FUNCTION g_memdup ##### -->
-<para>
-Allocates @byte_size bytes of memory, and copies @byte_size bytes into it
-from @mem. If @mem is %NULL it returns %NULL.
-</para>
-
- mem: the memory to copy.
- byte_size: the number of bytes to copy.
- Returns: a pointer to the newly-allocated copy of the memory, or %NULL if @mem
-is %NULL.
-
-
-<!-- ##### STRUCT GMemVTable ##### -->
-<para>
-A set of functions used to perform memory allocation. The same #GMemVTable must
-be used for all allocations in the same program; a call to g_mem_set_vtable(),
-if it exists, should be prior to any use of GLib.
-</para>
-
- malloc: function to use for allocating memory.
- realloc: function to use for reallocating memory.
- free: function to use to free memory.
- calloc: function to use for allocating zero-filled memory.
- try_malloc: function to use for allocating memory without a default error handler.
- try_realloc: function to use for reallocating memory without a default error handler.
-
-<!-- ##### FUNCTION g_mem_set_vtable ##### -->
-<para>
-Sets the #GMemVTable to use for memory allocation. You can use this to provide
-custom memory allocation routines. <emphasis>This function must be called 
-before using any other GLib functions.</emphasis> The @vtable only needs to 
-provide malloc(), realloc(), and free() functions; GLib can provide default 
-implementations of the others. The malloc() and realloc() implementations 
-should return %NULL on failure, GLib will handle error-checking for you. 
- vtable is copied, so need not persist after this function has been called.
-</para>
-
- vtable: table of memory allocation routines.
-
-
-<!-- ##### FUNCTION g_mem_is_system_malloc ##### -->
-<para>
-
-</para>
-
- void: 
- Returns: 
-
-
-<!-- ##### VARIABLE glib_mem_profiler_table ##### -->
-<para>
-A #GMemVTable containing profiling variants of the memory
-allocation functions. Use them together with g_mem_profile()
-in order to get information about the memory allocation pattern
-of your program.
-</para>
-
-
-<!-- ##### FUNCTION g_mem_profile ##### -->
-<para>
-Outputs a summary of memory usage.
-</para>
-<para>
-It outputs the frequency of allocations of different sizes,
-the total number of bytes which have been allocated,
-the total number of bytes which have been freed,
-and the difference between the previous two values, i.e. the number of bytes
-still in use.
-</para>
-<para>
-Note that this function will not output anything unless you have
-previously installed the #glib_mem_profiler_table with g_mem_set_vtable().
-</para>
-
- void: 
-
-
diff --git a/glib/galloca.h b/glib/galloca.h
index 356587f..8876836 100644
--- a/glib/galloca.h
+++ b/glib/galloca.h
@@ -57,7 +57,54 @@ G_END_DECLS
 # endif /* !_MSC_VER && !__DMC__ */
 #endif /* !__GNUC__ && !GLIB_HAVE_ALLOCA_H */
 
+/**
+ * g_alloca:
+ * @size: number of bytes to allocate.
+ * 
+ * Allocates @size bytes on the stack; these bytes will be freed when the current
+ * stack frame is cleaned up. This macro essentially just wraps the alloca()
+ * function present on most UNIX variants.
+ * Thus it provides the same advantages and pitfalls as alloca():
+ * <variablelist>
+ *   <varlistentry><term></term><listitem><para>
+ *     + alloca() is very fast, as on most systems it's implemented by just adjusting
+ *     the stack pointer register.
+ *   </para></listitem></varlistentry>
+ *   <varlistentry><term></term><listitem><para>
+ *     + It doesn't cause any memory fragmentation, within its scope, separate alloca()
+ *     blocks just build up and are released together at function end.
+ *   </para></listitem></varlistentry>
+ *   <varlistentry><term></term><listitem><para>
+ *     - Allocation sizes have to fit into the current stack frame. For instance in a
+ *       threaded environment on Linux, the per-thread stack size is limited to 2 Megabytes,
+ *       so be sparse with alloca() uses.
+ *   </para></listitem></varlistentry>
+ *   <varlistentry><term></term><listitem><para>
+ *     - Allocation failure due to insufficient stack space is not indicated with a %NULL
+ *       return like e.g. with malloc(). Instead, most systems probably handle it the same
+ *       way as out of stack space situations from infinite function recursion, i.e.
+ *       with a segmentation fault.
+ *   </para></listitem></varlistentry>
+ *   <varlistentry><term></term><listitem><para>
+ *     - Special care has to be taken when mixing alloca() with GNU C variable sized arrays.
+ *       Stack space allocated with alloca() in the same scope as a variable sized array
+ *       will be freed together with the variable sized array upon exit of that scope, and
+ *       not upon exit of the enclosing function scope.
+ *   </para></listitem></varlistentry>
+ * </variablelist>
+ * 
+ * Returns: space for @size bytes, allocated on the stack
+ */
 #define g_alloca(size)		 alloca (size)
+/**
+ * g_newa:
+ * @struct_type: Type of memory chunks to be allocated
+ * @n_structs: Number of chunks to be allocated
+ * 
+ * Wraps g_alloca() in a more typesafe manner.
+ * 
+ * Returns: Pointer to stack space for @n_structs chunks of type @struct_type
+ */
 #define g_newa(struct_type, n_structs)	((struct_type*) g_alloca (sizeof (struct_type) * (gsize) (n_structs)))
 
 #endif /* __G_ALLOCA_H__ */
diff --git a/glib/gmem.c b/glib/gmem.c
index 20c76dc..991a503 100644
--- a/glib/gmem.c
+++ b/glib/gmem.c
@@ -121,7 +121,37 @@ static GMemVTable glib_mem_vtable = {
   standard_try_realloc,
 };
 
+/**
+ * SECTION:memory
+ * @Short_Description: general memory-handling
+ * @Title: Memory Allocation
+ * 
+ * These functions provide support for allocating and freeing memory.
+ * 
+ * <note>
+ * If any call to allocate memory fails, the application is terminated.
+ * This also means that there is no need to check if the call succeeded.
+ * </note>
+ * 
+ * <note>
+ * It's important to match g_malloc() with g_free(), plain malloc() with free(),
+ * and (if you're using C++) new with delete and new[] with delete[]. Otherwise
+ * bad things can happen, since these allocators may use different memory
+ * pools (and new/delete call constructors and destructors). See also
+ * g_mem_set_vtable().
+ * </note>
+ */
+
 /* --- functions --- */
+/**
+ * g_malloc:
+ * @n_bytes: the number of bytes to allocate
+ * 
+ * Allocates @n_bytes bytes of memory.
+ * If @n_bytes is 0 it returns %NULL.
+ * 
+ * Returns: a pointer to the allocated memory
+ */
 gpointer
 g_malloc (gsize n_bytes)
 {
@@ -145,6 +175,15 @@ g_malloc (gsize n_bytes)
   return NULL;
 }
 
+/**
+ * g_malloc0:
+ * @n_bytes: the number of bytes to allocate
+ * 
+ * Allocates @n_bytes bytes of memory, initialized to 0's.
+ * If @n_bytes is 0 it returns %NULL.
+ * 
+ * Returns: a pointer to the allocated memory
+ */
 gpointer
 g_malloc0 (gsize n_bytes)
 {
@@ -168,6 +207,19 @@ g_malloc0 (gsize n_bytes)
   return NULL;
 }
 
+/**
+ * g_realloc:
+ * @mem: the memory to reallocate
+ * @n_bytes: new size of the memory in bytes
+ * 
+ * Reallocates the memory pointed to by @mem, so that it now has space for
+ * @n_bytes bytes of memory. It returns the new address of the memory, which may
+ * have been moved. @mem may be %NULL, in which case it's considered to
+ * have zero-length. @n_bytes may be 0, in which case %NULL will be returned
+ * and @mem will be freed unless it is %NULL.
+ * 
+ * Returns: the new address of the allocated memory
+ */
 gpointer
 g_realloc (gpointer mem,
 	   gsize    n_bytes)
@@ -195,6 +247,13 @@ g_realloc (gpointer mem,
   return NULL;
 }
 
+/**
+ * g_free:
+ * @mem: the memory to free
+ * 
+ * Frees the memory pointed to by @mem.
+ * If @mem is %NULL it simply returns.
+ */
 void
 g_free (gpointer mem)
 {
@@ -205,6 +264,15 @@ g_free (gpointer mem)
   TRACE(GLIB_MEM_FREE((void*) mem));
 }
 
+/**
+ * g_try_malloc:
+ * @n_bytes: number of bytes to allocate.
+ * 
+ * Attempts to allocate @n_bytes, and returns %NULL on failure.
+ * Contrast with g_malloc(), which aborts the program on failure.
+ * 
+ * Returns: the allocated memory, or %NULL.
+ */
 gpointer
 g_try_malloc (gsize n_bytes)
 {
@@ -222,6 +290,16 @@ g_try_malloc (gsize n_bytes)
   return mem;
 }
 
+/**
+ * g_try_malloc0:
+ * @n_bytes: number of bytes to allocate
+ * 
+ * Attempts to allocate @n_bytes, initialized to 0's, and returns %NULL on
+ * failure. Contrast with g_malloc0(), which aborts the program on failure.
+ * 
+ * Since: 2.8
+ * Returns: the allocated memory, or %NULL
+ */
 gpointer
 g_try_malloc0 (gsize n_bytes)
 {
@@ -240,6 +318,17 @@ g_try_malloc0 (gsize n_bytes)
   return mem;
 }
 
+/**
+ * g_try_realloc:
+ * @mem: previously-allocated memory, or %NULL.
+ * @n_bytes: number of bytes to allocate.
+ * 
+ * Attempts to realloc @mem to a new size, @n_bytes, and returns %NULL
+ * on failure. Contrast with g_realloc(), which aborts the program
+ * on failure. If @mem is %NULL, behaves the same as g_try_malloc().
+ * 
+ * Returns: the allocated memory, or %NULL.
+ */
 gpointer
 g_try_realloc (gpointer mem,
 	       gsize    n_bytes)
@@ -265,6 +354,17 @@ g_try_realloc (gpointer mem,
 
 #define SIZE_OVERFLOWS(a,b) (G_UNLIKELY ((b) > 0 && (a) > G_MAXSIZE / (b)))
 
+/**
+ * g_malloc_n:
+ * @n_blocks: the number of blocks to allocate
+ * @n_block_bytes: the size of each block in bytes
+ * 
+ * This function is similar to g_malloc(), allocating (@n_blocks * @n_block_bytes) bytes,
+ * but care is taken to detect possible overflow during multiplication.
+ * 
+ * Since: 2.24
+ * Returns: a pointer to the allocated memory
+ */
 gpointer
 g_malloc_n (gsize n_blocks,
 	    gsize n_block_bytes)
@@ -281,6 +381,17 @@ g_malloc_n (gsize n_blocks,
   return g_malloc (n_blocks * n_block_bytes);
 }
 
+/**
+ * g_malloc0_n:
+ * @n_blocks: the number of blocks to allocate
+ * @n_block_bytes: the size of each block in bytes
+ * 
+ * This function is similar to g_malloc0(), allocating (@n_blocks * @n_block_bytes) bytes,
+ * but care is taken to detect possible overflow during multiplication.
+ * 
+ * Since: 2.24
+ * Returns: a pointer to the allocated memory
+ */
 gpointer
 g_malloc0_n (gsize n_blocks,
 	     gsize n_block_bytes)
@@ -297,6 +408,18 @@ g_malloc0_n (gsize n_blocks,
   return g_malloc0 (n_blocks * n_block_bytes);
 }
 
+/**
+ * g_realloc_n:
+ * @mem: the memory to reallocate
+ * @n_blocks: the number of blocks to allocate
+ * @n_block_bytes: the size of each block in bytes
+ * 
+ * This function is similar to g_realloc(), allocating (@n_blocks * @n_block_bytes) bytes,
+ * but care is taken to detect possible overflow during multiplication.
+ * 
+ * Since: 2.24
+ * Returns: the new address of the allocated memory
+ */
 gpointer
 g_realloc_n (gpointer mem,
 	     gsize    n_blocks,
@@ -314,6 +437,17 @@ g_realloc_n (gpointer mem,
   return g_realloc (mem, n_blocks * n_block_bytes);
 }
 
+/**
+ * g_try_malloc_n:
+ * @n_blocks: the number of blocks to allocate
+ * @n_block_bytes: the size of each block in bytes
+ * 
+ * This function is similar to g_try_malloc(), allocating (@n_blocks * @n_block_bytes) bytes,
+ * but care is taken to detect possible overflow during multiplication.
+ * 
+ * Since: 2.24
+ * Returns: the allocated memory, or %NULL.
+ */
 gpointer
 g_try_malloc_n (gsize n_blocks,
 		gsize n_block_bytes)
@@ -324,6 +458,17 @@ g_try_malloc_n (gsize n_blocks,
   return g_try_malloc (n_blocks * n_block_bytes);
 }
 
+/**
+ * g_try_malloc0_n:
+ * @n_blocks: the number of blocks to allocate
+ * @n_block_bytes: the size of each block in bytes
+ * 
+ * This function is similar to g_try_malloc0(), allocating (@n_blocks * @n_block_bytes) bytes,
+ * but care is taken to detect possible overflow during multiplication.
+ * 
+ * Since: 2.24
+ * Returns: the allocated memory, or %NULL
+ */
 gpointer
 g_try_malloc0_n (gsize n_blocks,
 		 gsize n_block_bytes)
@@ -334,6 +479,18 @@ g_try_malloc0_n (gsize n_blocks,
   return g_try_malloc0 (n_blocks * n_block_bytes);
 }
 
+/**
+ * g_try_realloc_n:
+ * @mem: previously-allocated memory, or %NULL.
+ * @n_blocks: the number of blocks to allocate
+ * @n_block_bytes: the size of each block in bytes
+ * 
+ * This function is similar to g_try_realloc(), allocating (@n_blocks * @n_block_bytes) bytes,
+ * but care is taken to detect possible overflow during multiplication.
+ * 
+ * Since: 2.24
+ * Returns: the allocated memory, or %NULL.
+ */
 gpointer
 g_try_realloc_n (gpointer mem,
 		 gsize    n_blocks,
@@ -367,7 +524,7 @@ static gboolean vtable_set = FALSE;
  * 
  * Checks whether the allocator used by g_malloc() is the system's
  * malloc implementation. If it returns %TRUE memory allocated with
- * malloc() can be used interchangeable with memory allocated using g_malloc(). 
+ * malloc() can be used interchangeable with memory allocated using g_malloc().
  * This function is useful for avoiding an extra copy of allocated memory returned
  * by a non-GLib-based API.
  *
@@ -381,6 +538,18 @@ g_mem_is_system_malloc (void)
   return !vtable_set;
 }
 
+/**
+ * g_mem_set_vtable:
+ * @vtable: table of memory allocation routines.
+ * 
+ * Sets the #GMemVTable to use for memory allocation. You can use this to provide
+ * custom memory allocation routines. <emphasis>This function must be called
+ * before using any other GLib functions.</emphasis> The @vtable only needs to
+ * provide malloc(), realloc(), and free() functions; GLib can provide default
+ * implementations of the others. The malloc() and realloc() implementations
+ * should return %NULL on failure, GLib will handle error-checking for you.
+ * @vtable is copied, so need not persist after this function has been called.
+ */
 void
 g_mem_set_vtable (GMemVTable *vtable)
 {
@@ -406,6 +575,14 @@ g_mem_set_vtable (GMemVTable *vtable)
 
 /* --- memory profiling and checking --- */
 #ifdef	G_DISABLE_CHECKS
+/**
+ * glib_mem_profiler_table:
+ * 
+ * A #GMemVTable containing profiling variants of the memory
+ * allocation functions. Use them together with g_mem_profile()
+ * in order to get information about the memory allocation pattern
+ * of your program.
+ */
 GMemVTable *glib_mem_profiler_table = &glib_mem_vtable;
 void
 g_mem_profile (void)
@@ -521,6 +698,22 @@ profile_print_locked (guint   *local_data,
     g_print (" --- none ---\n");
 }
 
+/**
+ * g_mem_profile:
+ * @void:
+ * 
+ * Outputs a summary of memory usage.
+ * 
+ * It outputs the frequency of allocations of different sizes,
+ * the total number of bytes which have been allocated,
+ * the total number of bytes which have been freed,
+ * and the difference between the previous two values, i.e. the number of bytes
+ * still in use.
+ * 
+ * Note that this function will not output anything unless you have
+ * previously installed the #glib_mem_profiler_table with g_mem_set_vtable().
+ */
+
 void
 g_mem_profile (void)
 {
@@ -1251,6 +1444,12 @@ g_allocator_free (GAllocator *allocator)
 #ifdef ENABLE_GC_FRIENDLY_DEFAULT
 gboolean g_mem_gc_friendly = TRUE;
 #else
+/**
+ * g_mem_gc_friendly:
+ * 
+ * This variable is %TRUE if the <envar>G_DEBUG</envar> environment variable
+ * includes the key <link linkend="G_DEBUG">gc-friendly</link>.
+ */
 gboolean g_mem_gc_friendly = FALSE;
 #endif
 
diff --git a/glib/gmem.h b/glib/gmem.h
index a28ee7c..cb39d42 100644
--- a/glib/gmem.h
+++ b/glib/gmem.h
@@ -36,10 +36,29 @@
 
 G_BEGIN_DECLS
 
+/**
+ * GMemVTable:
+ * @malloc: function to use for allocating memory.
+ * @realloc: function to use for reallocating memory.
+ * @free: function to use to free memory.
+ * @calloc: function to use for allocating zero-filled memory.
+ * @try_malloc: function to use for allocating memory without a default error handler.
+ * @try_realloc: function to use for reallocating memory without a default error handler.
+ * 
+ * A set of functions used to perform memory allocation. The same #GMemVTable must
+ * be used for all allocations in the same program; a call to g_mem_set_vtable(),
+ * if it exists, should be prior to any use of GLib.
+ */
 typedef struct _GMemVTable GMemVTable;
 
 
 #if GLIB_SIZEOF_VOID_P > GLIB_SIZEOF_LONG
+/**
+ * G_MEM_ALIGN:
+ * 
+ * Indicates the number of bytes to which memory will be aligned on the
+ * current platform.
+ */
 #  define G_MEM_ALIGN	GLIB_SIZEOF_VOID_P
 #else	/* GLIB_SIZEOF_VOID_P <= GLIB_SIZEOF_LONG */
 #  define G_MEM_ALIGN	GLIB_SIZEOF_LONG
@@ -120,11 +139,98 @@ gpointer g_try_realloc_n  (gpointer	 mem,
 
 #endif
 
+/**
+ * g_new:
+ * @struct_type: the type of the elements to allocate
+ * @n_structs: the number of elements to allocate
+ * 
+ * Allocates @n_structs elements of type @struct_type.
+ * The returned pointer is cast to a pointer to the given type.
+ * If @n_structs is 0 it returns %NULL.
+ * Care is taken to avoid overflow when calculating the size of the allocated block.
+ * 
+ * Since the returned pointer is already casted to the right type,
+ * it is normally unnecessary to cast it explicitly, and doing
+ * so might hide memory allocation errors.
+ * 
+ * Returns: a pointer to the allocated memory, cast to a pointer to @struct_type
+ */
 #define g_new(struct_type, n_structs)			_G_NEW (struct_type, n_structs, malloc)
+/**
+ * g_new0:
+ * @struct_type: the type of the elements to allocate.
+ * @n_structs: the number of elements to allocate.
+ * 
+ * Allocates @n_structs elements of type @struct_type, initialized to 0's.
+ * The returned pointer is cast to a pointer to the given type.
+ * If @n_structs is 0 it returns %NULL.
+ * Care is taken to avoid overflow when calculating the size of the allocated block.
+ * 
+ * Since the returned pointer is already casted to the right type,
+ * it is normally unnecessary to cast it explicitly, and doing
+ * so might hide memory allocation errors.
+ * 
+ * Returns: a pointer to the allocated memory, cast to a pointer to @struct_type.
+ */
 #define g_new0(struct_type, n_structs)			_G_NEW (struct_type, n_structs, malloc0)
+/**
+ * g_renew:
+ * @struct_type: the type of the elements to allocate
+ * @mem: the currently allocated memory
+ * @n_structs: the number of elements to allocate
+ * 
+ * Reallocates the memory pointed to by @mem, so that it now has space for
+ * @n_structs elements of type @struct_type. It returns the new address of
+ * the memory, which may have been moved.
+ * Care is taken to avoid overflow when calculating the size of the allocated block.
+ * 
+ * Returns: a pointer to the new allocated memory, cast to a pointer to @struct_type
+ */
 #define g_renew(struct_type, mem, n_structs)		_G_RENEW (struct_type, mem, n_structs, realloc)
+/**
+ * g_try_new:
+ * @struct_type: the type of the elements to allocate
+ * @n_structs: the number of elements to allocate
+ * 
+ * Attempts to allocate @n_structs elements of type @struct_type, and returns
+ * %NULL on failure. Contrast with g_new(), which aborts the program on failure.
+ * The returned pointer is cast to a pointer to the given type.
+ * The function returns %NULL when @n_structs is 0 of if an overflow occurs.
+ * 
+ * Since: 2.8
+ * Returns: a pointer to the allocated memory, cast to a pointer to @struct_type
+ */
 #define g_try_new(struct_type, n_structs)		_G_NEW (struct_type, n_structs, try_malloc)
+/**
+ * g_try_new0:
+ * @struct_type: the type of the elements to allocate
+ * @n_structs: the number of elements to allocate
+ * 
+ * Attempts to allocate @n_structs elements of type @struct_type, initialized
+ * to 0's, and returns %NULL on failure. Contrast with g_new0(), which aborts
+ * the program on failure.
+ * The returned pointer is cast to a pointer to the given type.
+ * The function returns %NULL when @n_structs is 0 of if an overflow occurs.
+ * 
+ * Since: 2.8
+ * Returns: a pointer to the allocated memory, cast to a pointer to @struct_type
+ */
 #define g_try_new0(struct_type, n_structs)		_G_NEW (struct_type, n_structs, try_malloc0)
+/**
+ * g_try_renew:
+ * @struct_type: the type of the elements to allocate
+ * @mem: the currently allocated memory
+ * @n_structs: the number of elements to allocate
+ * 
+ * Attempts to reallocate the memory pointed to by @mem, so that it now has
+ * space for @n_structs elements of type @struct_type, and returns %NULL on
+ * failure. Contrast with g_renew(), which aborts the program on failure.
+ * It returns the new address of the memory, which may have been moved.
+ * The function returns %NULL if an overflow occurs.
+ * 
+ * Since: 2.8
+ * Returns: a pointer to the new allocated memory, cast to a pointer to @struct_type
+ */
 #define g_try_renew(struct_type, mem, n_structs)	_G_RENEW (struct_type, mem, n_structs, try_realloc)
 
 
diff --git a/glib/gstrfuncs.c b/glib/gstrfuncs.c
index d7e82d1..6c1166a 100644
--- a/glib/gstrfuncs.c
+++ b/glib/gstrfuncs.c
@@ -107,6 +107,17 @@ g_strdup (const gchar *str)
   return new_str;
 }
 
+/**
+ * g_memdup:
+ * @mem: the memory to copy.
+ * @byte_size: the number of bytes to copy.
+ * 
+ * Allocates @byte_size bytes of memory, and copies @byte_size bytes into it
+ * from @mem. If @mem is %NULL it returns %NULL.
+ * 
+ * Returns: a pointer to the newly-allocated copy of the memory, or %NULL if @mem
+ *  is %NULL.
+ */
 gpointer
 g_memdup (gconstpointer mem,
 	  guint         byte_size)
-- 
1.7.2.1