First batch of doxygen for wmem. Remove some things from README.wmem now that

they're in doxygen instead.

svn path=/trunk/; revision=49583

7 files changed, 192 insertions, 43 deletions

diff --git a/doc/README.wmem b/doc/README.wmem
index 9bdf4e4f7b..c2f10964e1 100644
--- a/doc/README.wmem
+++ b/doc/README.wmem
@@ -111,26 +111,10 @@ Sometimes (though hopefully rarely) it may be necessary to store data in a wmem
 pool that requires additional cleanup before it is freed. For example, perhaps
 you have a pointer to a file-handle that needs to be closed. In this case, you
 can register a callback with the wmem_register_cleanup_callback function
-declared in wmem_user_cb.h. This function takes as parameters:
- - the allocator
- - boolean indicating whether or not the callback should be recurring (ie
-   happens once if FALSE, or every time if TRUE)
- - the callback function (signature defined in wmem_user_cb.h)
- - a void user_data pointer
-
-Every time the memory in a pool is freed, all registered cleanup functions are
-called first, being passed:
- - a pointer to the allocator
- - a boolean indicating if this is just a free_all (FALSE) or if this was
-   triggered by destruction of the entire pool (TRUE) - mostly useful for
-   recurring callbacks
- - whatever user_data was registered with that callback.
-
-Note that the user_data pointer is not freed when a callback is finished, you
-have to do that yourself in the callback, or just allocate it in the
-appropriate wmem pool.
-
-Also note that callback calling order is not defined, you cannot rely on a
+declared in wmem_user_cb.h. Every time the memory in a pool is freed, all
+registered cleanup functions are called first.
+
+Note that callback calling order is not defined, you cannot rely on a
 certain callback being called before or after another.
 
 WARNING: Manually freeing or moving memory (with wmem_free or wmem_realloc)
@@ -152,22 +136,8 @@ pool to pick one.
 3.1 Available Allocator Back-Ends
 
 Each available allocator type has a corresponding entry in the
-wmem_allocator_type_t enumeration defined in wmem_core.h.
-
-The currently available allocators are:
- - WMEM_ALLOCATOR_SIMPLE (wmem_allocator_simple.*)
-        A trivial allocator that g_allocs requested memory and tracks
-        allocations via a GHashTable. As simple as possible, intended more as
-        a demo than for practical usage. Also has the benefit of being friendly
-        to tools like valgrind.
- - WMEM_ALLOCATOR_BLOCK (wmem_allocator_block.*)
-        A block allocator that grabs large chunks of memory at a time
-        (8 MB currently) and serves allocations out of those chunks.
-        Designed for efficiency, especially in the free_all operation.
- - WMEM_ALLOCATOR_STRICT (wmem_allocator_strict.*)
-        An allocator that does its best to find invalid memory usage via
-        things like canaries and scrubbing freed memory. Valgrind is the
-        better choice on platforms that support it.
+wmem_allocator_type_t enumeration defined in wmem_core.h. See the doxygen
+comments in that header file for details on each type.
 
 3.2 Creating a Pool
 
diff --git a/epan/wmem/wmem_core.h b/epan/wmem/wmem_core.h
index 238a57c89d..7e9862a08c 100644
--- a/epan/wmem/wmem_core.h
+++ b/epan/wmem/wmem_core.h
@@ -34,66 +34,164 @@
 extern "C" {
 #endif /* __cplusplus */
 
-/* Allocator structure and typedef */
+/** @defgroup wmem Wireshark Memory Manager
+ *
+ * Wmem is a memory management framework for Wireshark that makes it simple to
+ * write dissectors (and other 'user-space' code) that doesn't leak memory. The
+ * core module provides basic functions like malloc, realloc and free, but
+ * many other functions are available (see the "Modules" list at the top of
+ * the generated doxygen HTML).
+ *
+ * @{
+ */
+
 struct _wmem_allocator_t;
+/** A public opaque type representing one wmem allocation pool. */
 typedef struct _wmem_allocator_t wmem_allocator_t;
 
-/* Different types of allocators */
+/** An enumeration of the different types of available allocators. */
 typedef enum _wmem_allocator_type_t {
-    WMEM_ALLOCATOR_SIMPLE,
-    WMEM_ALLOCATOR_BLOCK,
-    WMEM_ALLOCATOR_STRICT
+    WMEM_ALLOCATOR_SIMPLE, /**< A trivial allocator that g_allocs requested
+               memory and tracks allocations via a GHashTable. As simple as
+               possible, intended more as a demo than for practical usage. Also
+               has the benefit of being friendly to tools like valgrind. */
+    WMEM_ALLOCATOR_BLOCK, /**< A block allocator that grabs large chunks of
+                memory at a time (8 MB currently) and serves allocations out of
+                those chunks. Designed for efficiency, especially in the
+                free_all operation. */
+    WMEM_ALLOCATOR_STRICT /**< An allocator that does its best to find invalid
+                memory usage via things like canaries and scrubbing freed
+                memory. Valgrind is the better choice on platforms that support
+                it. */
 } wmem_allocator_type_t;
 
+/** Allocate the requested amount of memory in the given pool.
+ *
+ * @param allocator The allocator object to use to allocate the memory.
+ * @param size The amount of memory to allocate.
+ * @return A void pointer to the newly allocated memory.
+ */
 WS_DLL_PUBLIC
 void *
 wmem_alloc(wmem_allocator_t *allocator, const size_t size)
 G_GNUC_MALLOC;
 
+/** Allocate memory sufficient to hold one object of the given type.
+ *
+ * @param allocator The allocator object to use to allocate the memory.
+ * @param type The type that the newly allocated memory will hold.
+ * @return A void pointer to the newly allocated memory.
+ */
 #define wmem_new(allocator, type) \
     ((type*)wmem_alloc((allocator), sizeof(type)))
 
+/** Allocate the requested amount of memory in the given pool. Initializes the
+ * allocated memory with zeroes.
+ *
+ * @param allocator The allocator object to use to allocate the memory.
+ * @param size The amount of memory to allocate.
+ * @return A void pointer to the newly allocated and zeroed memory.
+ */
 WS_DLL_PUBLIC
 void *
 wmem_alloc0(wmem_allocator_t *allocator, const size_t size)
 G_GNUC_MALLOC;
 
+/** Allocate memory sufficient to hold one object of the given type.
+ * Initializes the allocated memory with zeroes.
+ *
+ * @param allocator The allocator object to use to allocate the memory.
+ * @param type The type that the newly allocated memory will hold.
+ * @return A void pointer to the newly allocated and zeroed memory.
+ */
 #define wmem_new0(allocator, type) \
     ((type*)wmem_alloc0((allocator), sizeof(type)))
 
+/** Returns the allocated memory to the allocator. This function should only
+ * be called directly by allocators when the allocated block is sufficiently
+ * large that the reduced memory usage is worth the cost of the extra function
+ * call. It's usually easier to just let it get cleaned up when wmem_free_all()
+ * is called.
+ *
+ * @param allocator The allocator object used to originally allocate the memory.
+ * @param ptr The pointer to the memory block to free. After this function
+ * returns it no longer points to valid memory.
+ */
 WS_DLL_PUBLIC
 void
 wmem_free(wmem_allocator_t *allocator, void *ptr);
 
+/** Resizes a block of memory, potentially moving it if resizing it in place
+ * is not possible.
+ *
+ * @param allocator The allocator object used to originally allocate the memory.
+ * @param ptr The pointer to the memory block to resize.
+ * @param size The new size for the memory block.
+ * @return The new location of the memory block. If this is different from ptr
+ * then ptr no longer points to valid memory.
+ */
 WS_DLL_PUBLIC
 void *
 wmem_realloc(wmem_allocator_t *allocator, void *ptr, const size_t size)
 G_GNUC_MALLOC;
 
+/** Frees all the memory allocated in a pool. Depending on the allocator
+ * implementation used this can be significantly cheaper than calling
+ * wmem_free() on all the individual blocks. It also doesn't require you to have
+ * external pointers to those blocks.
+ *
+ * @param allocator The allocator to free the memory from.
+ */
 WS_DLL_PUBLIC
 void
 wmem_free_all(wmem_allocator_t *allocator);
 
+/** Triggers a garbage-collection in the allocator. This does not free any
+ * memory, but it can return unused blocks to the operating system or perform
+ * other optimizations.
+ *
+ * @param allocator The allocator in which to trigger the garbage collection.
+ */
 WS_DLL_PUBLIC
 void
 wmem_gc(wmem_allocator_t *allocator);
 
+/** Destroy the given allocator, freeing all memory allocated in it. Once this
+ * function has been called, no memory allocated with the allocator is valid.
+ *
+ * @param allocator The allocator to destroy.
+ */
 WS_DLL_PUBLIC
 void
 wmem_destroy_allocator(wmem_allocator_t *allocator);
 
+/** Create a new allocator of the given type. The type may be overridden by the
+ * WIRESHARK_DEBUG_WMEM_OVERRIDE environment variable.
+ *
+ * @param type The type of allocator to create.
+ * @return The new allocator.
+ */
 WS_DLL_PUBLIC
 wmem_allocator_t *
 wmem_allocator_new(const wmem_allocator_type_t type);
 
+/** Initialize the wmem subsystem. This must be called before any other wmem
+ * function, usually at the very beginning of your program.
+ */
 WS_DLL_LOCAL
 void
 wmem_init(void);
 
+/** Teardown the wmem subsystem. This must be called after all other wmem
+ * functions, usually at the very end of your program. This function will not
+ * destroy outstanding allocators, you must do that yourself.
+ */
 WS_DLL_LOCAL
 void
 wmem_cleanup(void);
 
+/** @} */
+
 #ifdef __cplusplus
 }
 #endif /* __cplusplus */
diff --git a/epan/wmem/wmem_slist.h b/epan/wmem/wmem_slist.h
index 3e9f1e0bfc..cd06e64d08 100644
--- a/epan/wmem/wmem_slist.h
+++ b/epan/wmem/wmem_slist.h
@@ -35,6 +35,15 @@
 extern "C" {
 #endif /* __cplusplus */
 
+/** @addtogroup wmem
+ *  @{
+ *    @defgroup wmem-slist Singly-Linked List
+ *
+ *    A singly-linked list implementation on top of wmem.
+ *
+ *    @{
+ */
+
 struct _wmem_slist_t;
 struct _wmem_slist_frame_t;
 
@@ -74,6 +83,9 @@ wmem_slist_t *
 wmem_slist_new(wmem_allocator_t *allocator)
 G_GNUC_MALLOC;
 
+/**   @}
+ *  @} */
+
 #ifdef __cplusplus
 }
 #endif /* __cplusplus */
diff --git a/epan/wmem/wmem_stack.h b/epan/wmem/wmem_stack.h
index 9a2a569de2..a85c47a3a5 100644
--- a/epan/wmem/wmem_stack.h
+++ b/epan/wmem/wmem_stack.h
@@ -36,6 +36,15 @@
 extern "C" {
 #endif /* __cplusplus */
 
+/** @addtogroup wmem
+ *  @{
+ *    @defgroup wmem-stack Stack
+ *
+ *    A stack implementation on top of wmem.
+ *
+ *    @{
+ */
+
 /* Wmem stack is implemented as a simple wrapper over Wmem slist */
 typedef wmem_slist_t wmem_stack_t;
 
@@ -55,6 +64,9 @@ wmem_stack_push(wmem_stack_t *stack, void *data);
 
 #define wmem_stack_new(ALLOCATOR) wmem_slist_new(ALLOCATOR)
 
+/**   @}
+ *  @} */
+
 #ifdef __cplusplus
 }
 #endif /* __cplusplus */
diff --git a/epan/wmem/wmem_strbuf.h b/epan/wmem/wmem_strbuf.h
index 3e24a36e75..4b0f498c99 100644
--- a/epan/wmem/wmem_strbuf.h
+++ b/epan/wmem/wmem_strbuf.h
@@ -35,6 +35,15 @@
 extern "C" {
 #endif /* __cplusplus */
 
+/** @addtogroup wmem
+ *  @{
+ *    @defgroup wmem-strbuf String Buffer
+ *
+ *    A string object implementation on top of wmem.
+ *
+ *    @{
+ */
+
 struct _wmem_strbuf_t;
 
 typedef struct _wmem_strbuf_t wmem_strbuf_t;
@@ -79,6 +88,9 @@ WS_DLL_PUBLIC
 gsize
 wmem_strbuf_get_len(wmem_strbuf_t *strbuf);
 
+/**   @}
+ *  @} */
+
 #ifdef __cplusplus
 }
 #endif /* __cplusplus */
diff --git a/epan/wmem/wmem_strutl.h b/epan/wmem/wmem_strutl.h
index cf412d6bf7..14f2702b77 100644
--- a/epan/wmem/wmem_strutl.h
+++ b/epan/wmem/wmem_strutl.h
@@ -34,6 +34,15 @@
 extern "C" {
 #endif /* __cplusplus */
 
+/** @addtogroup wmem
+ *  @{
+ *    @defgroup wmem-strutl String Utilities
+ *
+ *    A collection of utility function for operating on C strings with wmem.
+ *
+ *    @{
+ */
+
 WS_DLL_PUBLIC
 gchar *
 wmem_strdup(wmem_allocator_t *allocator, const gchar *src)
@@ -54,6 +63,9 @@ gchar *
 wmem_strdup_vprintf(wmem_allocator_t *allocator, const gchar *fmt, va_list ap)
 G_GNUC_MALLOC;
 
+/**   @}
+ *  @} */
+
 #ifdef __cplusplus
 }
 #endif /* __cplusplus */
diff --git a/epan/wmem/wmem_user_cb.h b/epan/wmem/wmem_user_cb.h
index 5a2ddbee71..929c8dc030 100644
--- a/epan/wmem/wmem_user_cb.h
+++ b/epan/wmem/wmem_user_cb.h
@@ -26,20 +26,53 @@
 #ifndef __WMEM_USER_CB_H__
 #define __WMEM_USER_CB_H__
 
+#include <glib.h>
+
 #ifdef __cplusplus
 extern "C" {
 #endif /* __cplusplus */
 
-#include <glib.h>
+/** @addtogroup wmem
+ *  @{
+ *    @defgroup wmem-user-cb User Callbacks
+ *
+ *    User callbacks.
+ *
+ *    @{
+ */
 
-/* User callback type for registering cleanup routines */
+/** Function signature for registered user callbacks.
+ *
+ * @param allocator The allocator that triggered this callback.
+ * @param final Whether this is was triggered due to the allocator being
+ *              destroyed (TRUE) or simply a call to wmem_free_all() (FALSE).
+ * @param user_data Whatever user_data was originally passed to the call to
+ *              wmem_register_cleanup_callback().
+ */
 typedef void (*wmem_user_cb_t) (wmem_allocator_t *, gboolean, void *);
 
+/** Register a callback function with the given allocator pool.
+ *
+ * @param allocator The allocator with which to register the callback.
+ * @param recurring If this is FALSE then the callback is called exactly once.
+ *                  If this is TRUE then the callback is called every time
+ *                  wmem_free_all() is called on the allocator, and one last
+ *                  time when wmem_destroy_allocator() is called on it.
+ * @param callback  The function to be called as the callback.
+ * @param user_data An arbitrary data pointer that is passed to the callback as
+ *                  a way to specify extra parameters or store extra data. Note
+ *                  that this pointer is not freed when a callback is finished,
+ *                  you have to do that yourself in the callback, or just
+ *                  allocate it in the appropriate wmem pool.
+ */
 WS_DLL_PUBLIC
 void
 wmem_register_cleanup_callback(wmem_allocator_t *allocator, gboolean recurring,
         wmem_user_cb_t callback, void *user_data);
 
+/**   @}
+ *  @} */
+
 #ifdef __cplusplus
 }
 #endif /* __cplusplus */