Improve the documentation of tvb_new_subset_ routines.

First mention tvbuff_new_subset_remaining(), as that's good enough for
most uses.

Then mention tvb_new_subset_length(), which is what most of the
remaining cases should use; we weren't even documenting it.

Then mention tvb_new_subset_length_caplen(); we want that to be used
only when *absolutely* necessary.

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

1 files changed, 36 insertions, 4 deletions

diff --git a/doc/README.dissector b/doc/README.dissector
index 778ef0775f..70a6875d1b 100644
--- a/doc/README.dissector
+++ b/doc/README.dissector
@@ -2301,13 +2301,45 @@ is expected to create a new tvbuff of type TVBUFF_SUBSET which
 contains the payload portion of the protocol (that is, the bytes
 that are relevant to the next dissector).
 
-The syntax for creating a new TVBUFF_SUBSET is:
+To create a new TVBUFF_SUBSET that begins at a specified offset in a
+parent tvbuff, and runs to the end of the parent tvbuff, the routine
+tvbuff_new_subset_remaining() is used:
 
-next_tvb = tvb_new_subset_length_caplen(tvb, offset, length, reported_length)
+    next_tvb = tvb_new_subset_remaining(tvb, offset);
 
-or, in the common case where it should just run to the end of the packet,
+Where:
+    tvb is the tvbuff that the dissector has been working on. It
+    can be a tvbuff of any type.
+
+    next_tvb is the new TVBUFF_SUBSET.
+
+    offset is the byte offset of 'tvb' at which the new tvbuff
+    should start.  The first byte is the 0th byte.
+
+To create a new TVBUFF_SUBSET that begins at a specified offset in a
+parent tvbuff, with a specified number of bytes in the payload, the
+routine tvbuff_new_subset_length() is used:
+
+    next_tvb = tvb_new_subset_length(tvb, offset, reported_length);
+
+Where:
+    tvb is the tvbuff that the dissector has been working on. It
+    can be a tvbuff of any type.
+
+    next_tvb is the new TVBUFF_SUBSET.
+
+    offset is the byte offset of 'tvb' at which the new tvbuff
+    should start.  The first byte is the 0th byte.
+
+    reported_length is the number of bytes that the current protocol
+    says should be in the payload.
+
+In the few cases where the number of bytes available in the new subset
+must be explicitly specified, rather than being calculated based on the
+number of bytes in the payload, the routine tvb_new_subset_length_caplen()
+is used:
 
-next_tvb = tvb_new_subset_remaining(tvb, offset)
+    next_tvb = tvb_new_subset_length_caplen(tvb, offset, length, reported_length);
 
 Where:
     tvb is the tvbuff that the dissector has been working on. It