Update some comments.

We no longer have TVBUFF_ values corresponding to different types of
tvbuff; we have, instead, a set of method pointers for the different
types.  Refer to the types by name, rather than by TVBUFF_ value.

Expand the description of some fields in the tvbuff structure.

Change-Id: I38b5281df247ddd66b4e39abfc129053a012d241
Reviewed-on: https://code.wireshark.org/review/27036
Reviewed-by: Guy Harris <guy@alum.mit.edu>

3 files changed, 38 insertions, 30 deletions

diff --git a/epan/tvbtest.c b/epan/tvbtest.c
index 832fc801a6..44380ae984 100644
--- a/epan/tvbtest.c
+++ b/epan/tvbtest.c
@@ -335,7 +335,7 @@ run_tests(void)
 		tvb_set_free_cb(tvb_large[i], g_free);
 	}
 
-	/* Test the TVBUFF_REAL_DATA objects. */
+	/* Test the "real" tvbuff objects. */
 	test(tvb_small[0], "Small 0", small[0], small_length[0], small_reported_length[0]);
 	test(tvb_small[1], "Small 1", small[1], small_length[1], small_reported_length[1]);
 	test(tvb_small[2], "Small 2", small[2], small_length[2], small_reported_length[2]);
@@ -374,7 +374,7 @@ run_tests(void)
 	tvb_subset[5]		  = tvb_new_subset_length_caplen(tvb_subset[2], 4, 8, 9);
 	subset[5]		  = &small[1][4];
 
-	/* Test the TVBUFF_SUBSET objects. */
+	/* Test the "subset" tvbuff objects. */
 	test(tvb_subset[0], "Subset 0", subset[0], subset_length[0], subset_reported_length[0]);
 	test(tvb_subset[1], "Subset 1", subset[1], subset_length[1], subset_reported_length[1]);
 	test(tvb_subset[2], "Subset 2", subset[2], subset_length[2], subset_reported_length[2]);
@@ -464,7 +464,7 @@ run_tests(void)
 	tvb_composite_append(tvb_comp[5], tvb_comp[3]);
 	tvb_composite_finalize(tvb_comp[5]);
 
-	/* Test the TVBUFF_COMPOSITE objects. */
+	/* Test the "composite" tvbuff objects. */
 	test(tvb_comp[0], "Composite 0", comp[0], comp_length[0], comp_reported_length[0]);
 	test(tvb_comp[1], "Composite 1", comp[1], comp_length[1], comp_reported_length[1]);
 	test(tvb_comp[2], "Composite 2", comp[2], comp_length[2], comp_reported_length[2]);
diff --git a/epan/tvbuff-int.h b/epan/tvbuff-int.h
index 38391e0295..6a5c1d4490 100644
--- a/epan/tvbuff-int.h
+++ b/epan/tvbuff-int.h
@@ -42,21 +42,29 @@ struct tvbuff {
 	guint			flags;
 	struct tvbuff		*ds_tvb;  /**< data source top-level tvbuff */
 
-	/** We're either a TVBUFF_REAL_DATA or a
-	 * TVBUFF_SUBSET that has a backing buffer that
-	 * has real_data != NULL, or a TVBUFF_COMPOSITE
-	 * which has flattened its data due to a call
-	 * to tvb_get_ptr().
+	/** Pointer to the data for this tvbuff.
+	 * It might be null, which either means that 1) it's a
+	 * zero-length tvbuff or 2) the tvbuff was lazily
+	 * constructed, so that we don't allocate a buffer of
+	 * backing data and fill it in unless we need that
+	 * data, e.g. when tvb_get_ptr() is called.
 	 */
 	const guint8		*real_data;
 
-	/** Length of virtual buffer (and/or real_data). */
+	/** Amount of data that's available from the capture
+	 * file.  This is the length of virtual buffer (and/or
+	 * real_data).  It may be less than the reported
+	 * length if this is from a packet that was cut short
+	 * by the capture process. */
 	guint			length;
 
-	/** Reported length. */
+	/** Amount of data that was reported as being in
+	 * the packet or other data that this represents.
+	 * As indicated above, it may be greater than the
+	 * amount of data that's available. */
 	guint			reported_length;
 
-	/* Offset from beginning of first TVBUFF_REAL. */
+	/* Offset from beginning of first "real" tvbuff. */
 	gint			raw_offset;
 };
 
diff --git a/epan/tvbuff.h b/epan/tvbuff.h
index 81e6a9bf78..2c4df952c1 100644
--- a/epan/tvbuff.h
+++ b/epan/tvbuff.h
@@ -79,18 +79,18 @@ typedef struct tvbuff tvbuff_t;
  * @{
  */
 
-/** TVBUFF_REAL_DATA contains a guint8* that points to real data.
+/** A "real" tvbuff contains a guint8* that points to real data.
  * The data is allocated and contiguous.
  *
- * TVBUFF_SUBSET has a backing tvbuff. The TVBUFF_SUBSET is a "window"
- * through which the program sees only a portion of the backing tvbuff.
+ * A "subset" tvbuff has a backing tvbuff. It is a "window" through
+ * which the program sees only a portion of the backing tvbuff.
  *
- * TVBUFF_COMPOSITE combines multiple tvbuffs sequentially to produce
- * a larger byte array.
+ * A "composite" tvbuff combines multiple tvbuffs sequentially to
+ * produce a larger byte array.
  *
  * tvbuff's of any type can be used as the backing-tvbuff of a
- * TVBUFF_SUBSET or as the member of a TVBUFF_COMPOSITE.
- * TVBUFF_COMPOSITEs can have member-tvbuffs of different types.
+ * "subset" tvbuff or as a member of a "composite" tvbuff.
+ * "composite" tvbuffs can have member-tvbuffs of different types.
  *
  * Once a tvbuff is create/initialized/finalized, the tvbuff is read-only.
  * That is, it cannot point to any other data. A new tvbuff must be created if
@@ -133,18 +133,18 @@ WS_DLL_PUBLIC void tvb_free_chain(tvbuff_t *tvb);
 /** Set a callback function to call when a tvbuff is actually freed
  * One argument is passed to that callback --- a void* that points
  * to the real data. Obviously, this only applies to a
- * TVBUFF_REAL_DATA tvbuff. */
+ * "real" tvbuff. */
 WS_DLL_PUBLIC void tvb_set_free_cb(tvbuff_t *tvb, const tvbuff_free_cb_t func);
 
-/** Attach a TVBUFF_REAL_DATA tvbuff to a parent tvbuff. This connection
- * is used during a tvb_free_chain()... the "child" TVBUFF_REAL_DATA acts
- * as if it is part of the chain-of-creation of the parent tvbuff, although it
+/** Attach a "real" tvbuff to a parent tvbuff. This connection is used
+ * during a tvb_free_chain()... the "child" "real" tvbuff acts as if it
+ * is part of the chain-of-creation of the parent tvbuff, although it
  * isn't. This is useful if you need to take the data from some tvbuff,
- * run some operation on it, like decryption or decompression, and make a new
- * tvbuff from it, yet want the new tvbuff to be part of the chain. The reality
- * is that the new tvbuff *is* part of the "chain of creation", but in a way
- * that these tvbuff routines are ignorant of. Use this function to make
- * the tvbuff routines knowledgable of this fact. */
+ * run some operation on it, like decryption or decompression, and make
+ * a new tvbuff from it, yet want the new tvbuff to be part of the chain.
+ * The reality is that the new tvbuff *is* part of the "chain of creation",
+ * but in a way that these tvbuff routines are ignorant of. Use this
+ * function to make the tvbuff routines knowledgable of this fact. */
 WS_DLL_PUBLIC void tvb_set_child_real_data_tvbuff(tvbuff_t *parent,
     tvbuff_t *child);
 
@@ -436,8 +436,8 @@ WS_DLL_PUBLIC guint32 tvb_get_bits(tvbuff_t *tvb, const guint bit_offset,
 /** Returns target for convenience. Does not suffer from possible
  * expense of tvb_get_ptr(), since this routine is smart enough
  * to copy data in chunks if the request range actually exists in
- * different TVBUFF_REAL_DATA tvbuffs. This function assumes that the
- * target memory is already allocated; it does not allocate or free the
+ * different "real" tvbuffs. This function assumes that the target
+ * memory is already allocated; it does not allocate or free the
  * target memory. */
 WS_DLL_PUBLIC void *tvb_memcpy(tvbuff_t *tvb, void *target, const gint offset,
     size_t length);
@@ -480,7 +480,7 @@ WS_DLL_PUBLIC void *tvb_memdup(wmem_allocator_t *scope, tvbuff_t *tvb,
  * guint8* points to read-only data that the tvbuff manages.
  *
  * Return a pointer into our buffer if the data asked for via 'offset'/'length'
- * is contiguous (which might not be the case for TVBUFF_COMPOSITE). If the
+ * is contiguous (which might not be the case for a "composite" tvbuff). If the
  * data is not contiguous, a tvb_memdup() is called for the entire buffer
  * and the pointer to the newly-contiguous data is returned. This dynamically-
  * allocated memory will be freed when the tvbuff is freed, after the