Fix some wmem-related documentation.

Discovered while reviewing Ibd3efb92a203861f507ce71bc8d04d19d9d38a93

Change-Id: Ie4dfc1b9b7a99f14657148ed5a935bbb079c2b4e
Reviewed-on: https://code.wireshark.org/review/415
Reviewed-by: Evan Huus <eapache@gmail.com>

2 files changed, 18 insertions, 11 deletions

diff --git a/doc/README.dissector b/doc/README.dissector
index 5f5eb789a5..ae6980e464 100644
--- a/doc/README.dissector
+++ b/doc/README.dissector
@@ -256,9 +256,8 @@ data from the specified tvbuff, starting at the specified offset, and containing
 the specified length worth of characters. Reads data in the specified encoding
 and produces UTF-8 in the buffer. See below for a list of input encoding values.
 
-The buffer is allocated by g_malloc() if scope is set to NULL (in that
-case memory must be explicitely freed), or with the allocator lifetime
-if scope is not NULL.
+The buffer is allocated in the given wmem scope (see README.wmem for more
+information).
 
 guint8 *tvb_get_stringz_enc(wmem_allocator_t *scope, tvbuff_t *tvb, const gint offset, gint *lengthp, const guint encoding);
 
@@ -270,9 +269,8 @@ specified encoding and produces UTF-8 in the buffer.  See below for a
 list of input encoding values.  "*lengthp" will be set to the length of
 the string, including the terminating null.
 
-The buffer is allocated by g_malloc() if scope is set to NULL (in that
-case memory must be explicitely freed), or with the allocator lifetime
-if scope is not NULL.
+The buffer is allocated in the given wmem scope (see README.wmem for more
+information).
 
 const guint8 *tvb_get_const_stringz(tvbuff_t *tvb, const gint offset, gint *lengthp);
 
@@ -303,9 +301,8 @@ gchar *tvb_get_ts_23_038_7bits_string(wmem_allocator_t *scope,
 tvb_get_ts_23_038_7bits_string() returns a string of a given number of
 characters and encoded according to 3GPP TS 23.038 7 bits alphabet.
 
-The buffer is allocated by g_malloc() if scope is set to NULL (in that
-case memory must be explicitely freed), or with the allocator lifetime
-if scope is not NULL.
+The buffer is allocated in the given wmem scope (see README.wmem for more
+information).
 
 Byte Array Accessors:
 
@@ -341,7 +338,8 @@ from the specified tvbuff, starting at the specified offset.
 
 guint8* tvb_memdup(wmem_allocator_t *scope, tvbuff_t *tvb, gint offset, gint length);
 
-Returns a buffer, allocated with "g_malloc()" if scope is NULL, or with the specified pool.
+Returns a buffer containing a copy of the given TVB bytes. The buffer is
+allocated in the given wmem scope (see README.wmem for more information).
 
 Pointer-retrieval:
 /* WARNING! Don't use this function.  There is almost always a better way.
diff --git a/doc/README.wmem b/doc/README.wmem
index 8012bea2e1..853d078997 100644
--- a/doc/README.wmem
+++ b/doc/README.wmem
@@ -68,6 +68,15 @@ next packet is dissected. This is, in fact, the scope of Wireshark's pinfo
 structure, so the pinfo struct has a 'pool' member which is a wmem pool scoped
 to the lifetime of the pinfo struct.
 
+2.1.3 NULL Pool
+
+Any function that takes a pointer to a wmem_allocator_t can also be passed NULL
+instead. In this case the memory is not allocated in a pool at all - it is
+manually managed, and *must* eventually be passed to wmem_free() in order to
+prevent memory leaks. Note that passing wmem_allocated memory directly to free()
+or g_free() is not safe; the backing type of manually managed memory may be
+changed without warning.
+
 2.2 API
 
 Full documentation for each function (parameters, return values, behaviours)
@@ -77,7 +86,7 @@ This is just an overview of which header files you should be looking at.
 2.2.1 Core API
 
 wmem_core.h
- - Basic memory management functions like malloc, realloc and free.
+ - Basic memory management functions (wmem_alloc, wmem_realloc, wmem_free).
 
 2.2.2 Strings