Enhance Lua API doc generator and add more API info

This enhances the Lua API doc generator Perl script to handle
meta-information in description comments, such as bold, italics,
raw code, version info, etc.

The supported markup and codes are documented in make-wsluarm.pl.

It's not beautiful Perl code (I don't know Perl), and I'd rather
do it using Lua, but I think keeping it Perl makes more sense in
the long run.

Change-Id: I477b3ebe770075dcea9ec52708e2d6fb5758d2f4
Reviewed-on: https://code.wireshark.org/review/802
Reviewed-by: Hadriel Kaplan <hadrielk@yahoo.com>
Reviewed-by: Anders Broman <a.broman58@gmail.com>

1 files changed, 134 insertions, 111 deletions

diff --git a/epan/wslua/wslua_tvb.c b/epan/wslua/wslua_tvb.c
index 1dae9c3461..bfad06c51e 100644
--- a/epan/wslua/wslua_tvb.c
+++ b/epan/wslua/wslua_tvb.c
@@ -37,9 +37,11 @@
 
 WSLUA_CLASS_DEFINE(ByteArray,FAIL_ON_NULL("ByteArray"),NOP);
 
-WSLUA_CONSTRUCTOR ByteArray_new(lua_State* L) { /* Creates a ByteArray Object */
-#define WSLUA_OPTARG_ByteArray_new_HEXBYTES 1 /* A string consisting of hexadecimal bytes like "00 B1 A2" or "1a2b3c4d" */
-#define WSLUA_OPTARG_ByteArray_new_SEPARATOR 2 /* A string separator between hex bytes/words (default=" "); or if the boolean value 'true' is used, then the first arg is treated as raw binary data */
+WSLUA_CONSTRUCTOR ByteArray_new(lua_State* L) { /* Creates a `ByteArray` object. */
+#define WSLUA_OPTARG_ByteArray_new_HEXBYTES 1 /* A string consisting of hexadecimal bytes like "00 B1 A2" or "1a2b3c4d". */
+#define WSLUA_OPTARG_ByteArray_new_SEPARATOR 2 /* A string separator between hex bytes/words (default=" "),
+                                                  or if the boolean value `true` is used, then the first argument
+                                                  is treated as raw binary data */
     GByteArray* ba = g_byte_array_new();
     const gchar* s;
     size_t len = 0;
@@ -88,9 +90,9 @@ static int ByteArray__gc(lua_State* L) {
 }
 
 WSLUA_METAMETHOD ByteArray__concat(lua_State* L) {
-	/* Concatenate two ByteArrays */
-#define WSLUA_ARG_ByteArray__cat_FIRST 1 /* First array */
-#define WSLUA_ARG_ByteArray__cat_SECOND 2 /* Second array */
+	/* Concatenate two `ByteArrays`. */
+#define WSLUA_ARG_ByteArray__cat_FIRST 1 /* First array. */
+#define WSLUA_ARG_ByteArray__cat_SECOND 2 /* Second array. */
 
     ByteArray ba1 = checkByteArray(L,WSLUA_ARG_ByteArray__cat_FIRST);
     ByteArray ba2 = checkByteArray(L,WSLUA_ARG_ByteArray__cat_SECOND);
@@ -101,12 +103,12 @@ WSLUA_METAMETHOD ByteArray__concat(lua_State* L) {
     g_byte_array_append(ba,ba2->data,ba2->len);
 
     pushByteArray(L,ba);
-    WSLUA_RETURN(1); /* The new composite ByteArray. */
+    WSLUA_RETURN(1); /* The new composite `ByteArray`. */
 }
 
 WSLUA_METHOD ByteArray_prepend(lua_State* L) {
-	/* Prepend a ByteArray to this ByteArray */
-#define WSLUA_ARG_ByteArray_prepend_PREPENDED 2 /* Array to be prepended */
+	/* Prepend a `ByteArray` to this `ByteArray`. */
+#define WSLUA_ARG_ByteArray_prepend_PREPENDED 2 /* `ByteArray` to be prepended. */
     ByteArray ba = checkByteArray(L,1);
     ByteArray ba2 = checkByteArray(L,WSLUA_ARG_ByteArray_prepend_PREPENDED);
 
@@ -116,8 +118,8 @@ WSLUA_METHOD ByteArray_prepend(lua_State* L) {
 }
 
 WSLUA_METHOD ByteArray_append(lua_State* L) {
-	/* Append a ByteArray to this ByteArray */
-#define WSLUA_ARG_ByteArray_append_APPENDED 2 /* Array to be appended */
+	/* Append a `ByteArray` to this `ByteArray`. */
+#define WSLUA_ARG_ByteArray_append_APPENDED 2 /* `ByteArray` to be appended. */
     ByteArray ba = checkByteArray(L,1);
     ByteArray ba2 = checkByteArray(L,WSLUA_ARG_ByteArray_append_APPENDED);
 
@@ -127,8 +129,8 @@ WSLUA_METHOD ByteArray_append(lua_State* L) {
 }
 
 WSLUA_METHOD ByteArray_set_size(lua_State* L) {
-	/* Sets the size of a ByteArray, either truncating it or filling it with zeros. */
-#define WSLUA_ARG_ByteArray_set_size_SIZE 2 /* New size of the array*/
+	/* Sets the size of a `ByteArray`, either truncating it or filling it with zeros. */
+#define WSLUA_ARG_ByteArray_set_size_SIZE 2 /* New size of the array. */
 
     ByteArray ba = checkByteArray(L,1);
     int siz = luaL_checkint(L,WSLUA_ARG_ByteArray_set_size_SIZE);
@@ -150,9 +152,9 @@ WSLUA_METHOD ByteArray_set_size(lua_State* L) {
 }
 
 WSLUA_METHOD ByteArray_set_index(lua_State* L) {
-	/* Sets the value of an index of a ByteArray. */
-#define WSLUA_ARG_ByteArray_set_index_INDEX 2 /* The position of the byte to be set */
-#define WSLUA_ARG_ByteArray_set_index_VALUE 3 /* The char value to set [0-255] */
+	/* Sets the value of an index of a `ByteArray`. */
+#define WSLUA_ARG_ByteArray_set_index_INDEX 2 /* The position of the byte to be set. */
+#define WSLUA_ARG_ByteArray_set_index_VALUE 3 /* The char value to set [0-255]. */
     ByteArray ba = checkByteArray(L,1);
     int idx = luaL_checkint(L,WSLUA_ARG_ByteArray_set_index_INDEX);
     int v = luaL_checkint(L,WSLUA_ARG_ByteArray_set_index_VALUE);
@@ -179,8 +181,8 @@ WSLUA_METHOD ByteArray_set_index(lua_State* L) {
 
 
 WSLUA_METHOD ByteArray_get_index(lua_State* L) {
-	/* Get the value of a byte in a ByteArray */
-#define WSLUA_ARG_ByteArray_get_index_INDEX 2 /* The position of the byte to get */
+	/* Get the value of a byte in a `ByteArray`. */
+#define WSLUA_ARG_ByteArray_get_index_INDEX 2 /* The position of the byte to get. */
     ByteArray ba = checkByteArray(L,1);
     int idx = luaL_checkint(L,WSLUA_ARG_ByteArray_get_index_INDEX);
 
@@ -199,18 +201,18 @@ WSLUA_METHOD ByteArray_get_index(lua_State* L) {
 }
 
 WSLUA_METHOD ByteArray_len(lua_State* L) {
-	/* Obtain the length of a ByteArray */
+	/* Obtain the length of a `ByteArray`. */
     ByteArray ba = checkByteArray(L,1);
 
     lua_pushnumber(L,(lua_Number)ba->len);
 
-    WSLUA_RETURN(1); /* The length of the ByteArray. */
+    WSLUA_RETURN(1); /* The length of the `ByteArray`. */
 }
 
 WSLUA_METHOD ByteArray_subset(lua_State* L) {
-	/* Obtain a segment of a ByteArray, as a new ByteArray. */
-#define WSLUA_ARG_ByteArray_set_index_OFFSET 2 /* The position of the first byte (0=first) */
-#define WSLUA_ARG_ByteArray_set_index_LENGTH 3 /* The length of the segment */
+	/* Obtain a segment of a `ByteArray`, as a new `ByteArray`. */
+#define WSLUA_ARG_ByteArray_set_index_OFFSET 2 /* The position of the first byte (0=first). */
+#define WSLUA_ARG_ByteArray_set_index_LENGTH 3 /* The length of the segment. */
     ByteArray ba = checkByteArray(L,1);
     int offset = luaL_checkint(L,WSLUA_ARG_ByteArray_set_index_OFFSET);
     int len = luaL_checkint(L,WSLUA_ARG_ByteArray_set_index_LENGTH);
@@ -226,11 +228,11 @@ WSLUA_METHOD ByteArray_subset(lua_State* L) {
 
     pushByteArray(L,sub);
 
-    WSLUA_RETURN(1); /* A ByteArray contaning the requested segment. */
+    WSLUA_RETURN(1); /* A `ByteArray` containing the requested segment. */
 }
 
 WSLUA_METHOD ByteArray_base64_decode(lua_State* L) {
-	/* Obtain a base64 decoded ByteArray */
+	/* Obtain a base64 decoded `ByteArray`. */
     ByteArray ba = checkByteArray(L,1);
     ByteArray ba2;
     gchar *data;
@@ -246,11 +248,11 @@ WSLUA_METHOD ByteArray_base64_decode(lua_State* L) {
     g_free(data);
 
     pushByteArray(L,ba2);
-    WSLUA_RETURN(1); /* The created ByteArray. */
+    WSLUA_RETURN(1); /* The created `ByteArray`. */
 }
 
 WSLUA_METHOD ByteArray_raw(lua_State* L) {
-    /* Obtain a Lua string of the binary bytes in a ByteArray. */
+    /* Obtain a Lua string of the binary bytes in a `ByteArray`. */
 #define WSLUA_OPTARG_ByteArray_raw_OFFSET 2 /* The position of the first byte (default=0/first). */
 #define WSLUA_OPTARG_ByteArray_raw_LENGTH 3 /* The length of the segment to get (default=all). */
     ByteArray ba = checkByteArray(L,1);
@@ -273,7 +275,7 @@ WSLUA_METHOD ByteArray_raw(lua_State* L) {
 }
 
 WSLUA_METHOD ByteArray_tohex(lua_State* L) {
-    /* Obtain a Lua string of the bytes in a ByteArray as hex-ascii, with given separator */
+    /* Obtain a Lua string of the bytes in a `ByteArray` as hex-ascii, with given separator */
 #define WSLUA_OPTARG_ByteArray_tohex_LOWERCASE 2 /* True to use lower-case hex characters (default=false). */
 #define WSLUA_OPTARG_ByteArray_tohex_SEPARATOR 3 /* A string separator to insert between hex bytes (default=nil). */
     ByteArray ba = checkByteArray(L,1);
@@ -287,18 +289,19 @@ WSLUA_METHOD ByteArray_tohex(lua_State* L) {
 
     wslua_bin2hex(L, ba->data, ba->len, lowercase, sep);
 
-    WSLUA_RETURN(1); /* A hex-ascii string representation of the ByteArray. */
+    WSLUA_RETURN(1); /* A hex-ascii string representation of the `ByteArray`. */
 }
 
 WSLUA_METAMETHOD ByteArray__tostring(lua_State* L) {
-	/* Obtain a Lua string containing the bytes in a ByteArray so that it can be used in display filters (e.g. "01FE456789AB") */
+	/* Obtain a Lua string containing the bytes in a `ByteArray` so that it can be used in
+       display filters (e.g. "01FE456789AB"). */
     ByteArray ba = checkByteArray(L,1);
 
     if (!ba) return 0;
 
     wslua_bin2hex(L, ba->data, ba->len, FALSE, NULL);
 
-    WSLUA_RETURN(1); /* A hex-ascii string representation of the ByteArray. */
+    WSLUA_RETURN(1); /* A hex-ascii string representation of the `ByteArray`. */
 }
 
 static int ByteArray_tvb (lua_State *L);
@@ -356,11 +359,16 @@ int ByteArray_register(lua_State* L) {
  */
 
 WSLUA_CLASS_DEFINE(Tvb,FAIL_ON_NULL_OR_EXPIRED("Tvb"),NOP);
-/* A Tvb represents the packet's buffer. It is passed as an argument to listeners and dissectors,
-and can be used to extract information (via TvbRange) from the packet's data. Beware that Tvbs are usable only by the current
-listener or dissector call and are destroyed as soon as the listener/dissector returns, so references
-to them are unusable once the function has returned.
-To create a tvbrange the tvb must be called with offset and length as optional arguments ( the offset defaults to 0 and the length to tvb:len() )*/
+/* A `Tvb` represents the packet's buffer. It is passed as an argument to listeners and dissectors,
+   and can be used to extract information (via `TvbRange`) from the packet's data.
+
+   To create a `TvbRange` the `Tvb` must be called with offset and length as optional arguments;
+   the offset defaults to 0 and the length to `tvb:len()`.
+
+   @warning `Tvb`s are usable only by the current listener or dissector call and are destroyed
+   as soon as the listener/dissector returns, so references to them are unusable once the function
+   has returned.
+*/
 
 static GPtrArray* outstanding_Tvb = NULL;
 static GPtrArray* outstanding_TvbRange = NULL;
@@ -421,7 +429,7 @@ Tvb* push_Tvb(lua_State* L, tvbuff_t* ws_tvb) {
  * ByteArray_tvb(name)
  */
 WSLUA_CONSTRUCTOR ByteArray_tvb (lua_State *L) {
-	/* Creates a new Tvb from a bytearray (it gets added to the current frame too) */
+	/* Creates a new `Tvb` from a `ByteArray` (it gets added to the current frame too). */
 #define WSLUA_ARG_ByteArray_tvb_NAME 2 /* The name to be given to the new data-source. */
     ByteArray ba = checkByteArray(L,1);
     const gchar* name = luaL_optstring(L,WSLUA_ARG_ByteArray_tvb_NAME,"Unnamed") ;
@@ -443,12 +451,12 @@ WSLUA_CONSTRUCTOR ByteArray_tvb (lua_State *L) {
 
     add_new_data_source(lua_pinfo, tvb->ws_tvb, name);
     PUSH_TVB(L,tvb);
-    WSLUA_RETURN(1); /* The created Tvb. */
+    WSLUA_RETURN(1); /* The created `Tvb`. */
 }
 
 WSLUA_CONSTRUCTOR TvbRange_tvb (lua_State *L) {
-	/* Creates a (sub)Tvb from a TvbRange */
-#define WSLUA_ARG_Tvb_new_subset_RANGE 1 /* The TvbRange from which to create the new Tvb. */
+	/* Creates a (sub)`Tvb` from a `TvbRange`. */
+#define WSLUA_ARG_Tvb_new_subset_RANGE 1 /* The `TvbRange` from which to create the new `Tvb`. */
 
     TvbRange tvbr = checkTvbRange(L,WSLUA_ARG_Tvb_new_subset_RANGE);
     Tvb tvb;
@@ -473,7 +481,8 @@ WSLUA_CONSTRUCTOR TvbRange_tvb (lua_State *L) {
 }
 
 WSLUA_METAMETHOD Tvb__tostring(lua_State* L) {
-	/* Convert the bytes of a Tvb into a string, to be used for debugging purposes as '...' will be appended in case the string is too long. */
+	/* Convert the bytes of a `Tvb` into a string, to be used for debugging purposes as '...'
+       will be appended in case the string is too long. */
     Tvb tvb = checkTvb(L,1);
     int len;
     gchar* str;
@@ -495,37 +504,38 @@ static int Tvb__gc(lua_State* L) {
 }
 
 WSLUA_METHOD Tvb_reported_len(lua_State* L) {
-	/* Obtain the reported (not captured) length of a TVB */
+	/* Obtain the reported (not captured) length of a `Tvb`. */
     Tvb tvb = checkTvb(L,1);
 
     lua_pushnumber(L,tvb_reported_length(tvb->ws_tvb));
-    WSLUA_RETURN(1); /* The length of the Tvb. */
+    WSLUA_RETURN(1); /* The reported length of the `Tvb`. */
 }
 
 WSLUA_METHOD Tvb_len(lua_State* L) {
-	/* Obtain the actual (captured) length of a TVB */
+	/* Obtain the actual (captured) length of a `Tvb`. */
     Tvb tvb = checkTvb(L,1);
 
     lua_pushnumber(L,tvb_length(tvb->ws_tvb));
-    WSLUA_RETURN(1); /* The length of the Tvb. */
+    WSLUA_RETURN(1); /* The captured length of the `Tvb`. */
 }
 
 WSLUA_METHOD Tvb_reported_length_remaining(lua_State* L) {
-	/* Obtain the reported (not captured) length of packet data to end of a TVB or -1 if the offset is beyond the end of the TVB */
+	/* Obtain the reported (not captured) length of packet data to end of a `Tvb` or -1 if the
+       offset is beyond the end of the `Tvb`. */
 #define Tvb_reported_length_remaining_OFFSET 2 /* offset */
     Tvb tvb = checkTvb(L,1);
     int offset = luaL_optint(L, Tvb_reported_length_remaining_OFFSET, 0);
 
     lua_pushnumber(L,tvb_reported_length_remaining(tvb->ws_tvb, offset));
-    WSLUA_RETURN(1); /* The length of the Tvb. */
+    WSLUA_RETURN(1); /* The captured length of the `Tvb`. */
 }
 
 WSLUA_METHOD Tvb_offset(lua_State* L) {
-	/* Returns the raw offset (from the beginning of the source Tvb) of a sub Tvb. */
+	/* Returns the raw offset (from the beginning of the source `Tvb`) of a sub `Tvb`. */
     Tvb tvb = checkTvb(L,1);
 
     lua_pushnumber(L,tvb_raw_offset(tvb->ws_tvb));
-    WSLUA_RETURN(1); /* The raw offset of the Tvb. */
+    WSLUA_RETURN(1); /* The raw offset of the `Tvb`. */
 }
 
 
@@ -538,9 +548,10 @@ WSLUA_METAMETHOD Tvb__call(lua_State* L) {
 
 WSLUA_CLASS_DEFINE(TvbRange,FAIL_ON_NULL("TvbRange"),NOP);
 /*
-  A TvbRange represents a usable range of a Tvb and is used to extract data from the Tvb that generated it
-  TvbRanges are created by calling a tvb (e.g. tvb(offset,length)). If the TvbRange span is outside the
-  Tvb's range the creation will cause a runtime error.
+  A `TvbRange` represents a usable range of a `Tvb` and is used to extract data from the `Tvb` that generated it.
+
+  `TvbRange`s are created by calling a `Tvb` (e.g. 'tvb(offset,length)'). If the `TvbRange` span is outside the
+  `Tvb`'s range the creation will cause a runtime error.
  */
 
 gboolean push_TvbRange(lua_State* L, tvbuff_t* ws_tvb, int offset, int len) {
@@ -577,9 +588,9 @@ gboolean push_TvbRange(lua_State* L, tvbuff_t* ws_tvb, int offset, int len) {
 
 
 WSLUA_METHOD Tvb_range(lua_State* L) {
-	/* Creates a tvbr from this Tvb. This is used also as the Tvb:__call() metamethod. */
-#define WSLUA_OPTARG_Tvb_range_OFFSET 2 /* The offset (in octets) from the beginning of the Tvb. Defaults to 0. */
-#define WSLUA_OPTARG_Tvb_range_LENGTH 3 /* The length (in octets) of the range. Defaults to until the end of the Tvb. */
+	/* Creates a `TvbRange` from this `Tvb`. */
+#define WSLUA_OPTARG_Tvb_range_OFFSET 2 /* The offset (in octets) from the beginning of the `Tvb`. Defaults to 0. */
+#define WSLUA_OPTARG_Tvb_range_LENGTH 3 /* The length (in octets) of the range. Defaults to until the end of the `Tvb`. */
 
     Tvb tvb = checkTvb(L,1);
     int offset = luaL_optint(L,WSLUA_OPTARG_Tvb_range_OFFSET,0);
@@ -593,7 +604,7 @@ WSLUA_METHOD Tvb_range(lua_State* L) {
 }
 
 WSLUA_METHOD Tvb_raw(lua_State* L) {
-    /* Obtain a Lua string of the binary bytes in a Tvb. */
+    /* Obtain a Lua string of the binary bytes in a `Tvb`. */
 #define WSLUA_OPTARG_Tvb_raw_OFFSET 2 /* The position of the first byte (default=0/first). */
 #define WSLUA_OPTARG_Tvb_raw_LENGTH 3 /* The length of the segment to get (default=all). */
     Tvb tvb = checkTvb(L,1);
@@ -624,7 +635,7 @@ WSLUA_METHOD Tvb_raw(lua_State* L) {
 
     lua_pushlstring(L, tvb_get_ptr(tvb->ws_tvb, offset, len), len);
 
-    WSLUA_RETURN(1); /* A Lua string of the binary bytes in the Tvb. */
+    WSLUA_RETURN(1); /* A Lua string of the binary bytes in the `Tvb`. */
 }
 
 WSLUA_METHODS Tvb_methods[] = {
@@ -653,7 +664,8 @@ int Tvb_register(lua_State* L) {
  *  get a Blefuscuoan unsigned integer from a tvb
  */
 WSLUA_METHOD TvbRange_uint(lua_State* L) {
-	/* Get a Big Endian (network order) unsigned integer from a TvbRange. The range must be 1, 2, 3 or 4 octets long. */
+	/* Get a Big Endian (network order) unsigned integer from a `TvbRange`.
+       The range must be 1, 2, 3 or 4 octets long. */
     TvbRange tvbr = checkTvbRange(L,1);
     if (!(tvbr && tvbr->tvb)) return 0;
     if (tvbr->tvb->expired) {
@@ -673,7 +685,7 @@ WSLUA_METHOD TvbRange_uint(lua_State* L) {
             return 1;
         case 4:
             lua_pushnumber(L,tvb_get_ntohl(tvbr->tvb->ws_tvb,tvbr->offset));
-            WSLUA_RETURN(1); /* The unsigned integer value */
+            WSLUA_RETURN(1); /* The unsigned integer value. */
             /*
              * XXX:
              *    lua uses double so we have 52 bits to play with
@@ -691,7 +703,8 @@ WSLUA_METHOD TvbRange_uint(lua_State* L) {
  *  get a Lilliputian unsigned integer from a tvb
  */
 WSLUA_METHOD TvbRange_le_uint(lua_State* L) {
-	/* Get a Little Endian unsigned integer from a TvbRange. The range must be 1, 2, 3 or 4 octets long. */
+	/* Get a Little Endian unsigned integer from a `TvbRange`.
+       The range must be 1, 2, 3 or 4 octets long. */
     TvbRange tvbr = checkTvbRange(L,1);
     if (!(tvbr && tvbr->tvb)) return 0;
     if (tvbr->tvb->expired) {
@@ -723,7 +736,8 @@ WSLUA_METHOD TvbRange_le_uint(lua_State* L) {
  *  get a Blefuscuoan unsigned 64 bit integer from a tvb
  */
 WSLUA_METHOD TvbRange_uint64(lua_State* L) {
-	/* Get a Big Endian (network order) unsigned 64 bit integer from a TvbRange. The range must be 1-8 octets long. */
+	/* Get a Big Endian (network order) unsigned 64 bit integer from a `TvbRange`, as a `UInt64` object.
+       The range must be 1-8 octets long. */
     TvbRange tvbr = checkTvbRange(L,1);
     if (!(tvbr && tvbr->tvb)) return 0;
     if (tvbr->tvb->expired) {
@@ -741,7 +755,7 @@ WSLUA_METHOD TvbRange_uint64(lua_State* L) {
         case 7:
         case 8: {
             pushUInt64(L,tvb_get_ntoh64(tvbr->tvb->ws_tvb,tvbr->offset));
-            WSLUA_RETURN(1);
+            WSLUA_RETURN(1); /* The `UInt64` object. */
         }
         default:
             luaL_error(L,"TvbRange:uint64() does not handle %d byte integers",tvbr->len);
@@ -753,7 +767,8 @@ WSLUA_METHOD TvbRange_uint64(lua_State* L) {
  *  get a Lilliputian unsigned 64 bit integer from a tvb
  */
 WSLUA_METHOD TvbRange_le_uint64(lua_State* L) {
-	/* Get a Little Endian unsigned 64 bit integer from a TvbRange. The range must be 1-8 octets long. */
+	/* Get a Little Endian unsigned 64 bit integer from a `TvbRange`, as a `UInt64` object.
+       The range must be 1-8 octets long. */
     TvbRange tvbr = checkTvbRange(L,1);
     if (!(tvbr && tvbr->tvb)) return 0;
     if (tvbr->tvb->expired) {
@@ -771,7 +786,7 @@ WSLUA_METHOD TvbRange_le_uint64(lua_State* L) {
         case 7:
         case 8: {
             pushUInt64(L,tvb_get_letoh64(tvbr->tvb->ws_tvb,tvbr->offset));
-            WSLUA_RETURN(1);
+            WSLUA_RETURN(1); /* The `UInt64` object. */
         }
         default:
             luaL_error(L,"TvbRange:le_uint64() does not handle %d byte integers",tvbr->len);
@@ -783,7 +798,8 @@ WSLUA_METHOD TvbRange_le_uint64(lua_State* L) {
  *  get a Blefuscuoan signed integer from a tvb
  */
 WSLUA_METHOD TvbRange_int(lua_State* L) {
-	/* Get a Big Endian (network order) signed integer from a TvbRange. The range must be 1, 2 or 4 octets long. */
+	/* Get a Big Endian (network order) signed integer from a `TvbRange`.
+       The range must be 1, 2 or 4 octets long. */
     TvbRange tvbr = checkTvbRange(L,1);
     if (!(tvbr && tvbr->tvb)) return 0;
     if (tvbr->tvb->expired) {
@@ -818,7 +834,8 @@ WSLUA_METHOD TvbRange_int(lua_State* L) {
  *  get a Lilliputian signed integer from a tvb
  */
 WSLUA_METHOD TvbRange_le_int(lua_State* L) {
-	/* Get a Little Endian signed integer from a TvbRange. The range must be 1, 2 or 4 octets long. */
+	/* Get a Little Endian signed integer from a `TvbRange`.
+       The range must be 1, 2 or 4 octets long. */
     TvbRange tvbr = checkTvbRange(L,1);
     if (!(tvbr && tvbr->tvb)) return 0;
     if (tvbr->tvb->expired) {
@@ -835,7 +852,7 @@ WSLUA_METHOD TvbRange_le_int(lua_State* L) {
             return 1;
         case 4:
             lua_pushnumber(L,(gint)tvb_get_letohl(tvbr->tvb->ws_tvb,tvbr->offset));
-            WSLUA_RETURN(1); /* The signed integer value */
+            WSLUA_RETURN(1); /* The signed integer value. */
         default:
             luaL_error(L,"TvbRange:le_int() does not handle %d byte integers",tvbr->len);
             return 0;
@@ -846,7 +863,8 @@ WSLUA_METHOD TvbRange_le_int(lua_State* L) {
  *  get a Blefuscuoan signed 64 bit integer from a tvb
  */
 WSLUA_METHOD TvbRange_int64(lua_State* L) {
-	/* Get a Big Endian (network order) signed 64 bit integer from a TvbRange. The range must be 1-8 octets long. */
+	/* Get a Big Endian (network order) signed 64 bit integer from a `TvbRange`, as an `Int64` object.
+       The range must be 1-8 octets long. */
     TvbRange tvbr = checkTvbRange(L,1);
     if (!(tvbr && tvbr->tvb)) return 0;
     if (tvbr->tvb->expired) {
@@ -864,7 +882,7 @@ WSLUA_METHOD TvbRange_int64(lua_State* L) {
         case 7:
         case 8: {
             pushInt64(L,(gint64)tvb_get_ntoh64(tvbr->tvb->ws_tvb,tvbr->offset));
-            WSLUA_RETURN(1);
+            WSLUA_RETURN(1); /* The `Int64` object. */
         }
         default:
             luaL_error(L,"TvbRange:int64() does not handle %d byte integers",tvbr->len);
@@ -876,7 +894,8 @@ WSLUA_METHOD TvbRange_int64(lua_State* L) {
  *  get a Lilliputian signed 64 bit integer from a tvb
  */
 WSLUA_METHOD TvbRange_le_int64(lua_State* L) {
-	/* Get a Little Endian signed 64 bit integer from a TvbRange. The range must be 1-8 octets long. */
+	/* Get a Little Endian signed 64 bit integer from a `TvbRange`, as an `Int64` object.
+       The range must be 1-8 octets long. */
     TvbRange tvbr = checkTvbRange(L,1);
     if (!(tvbr && tvbr->tvb)) return 0;
     if (tvbr->tvb->expired) {
@@ -894,7 +913,7 @@ WSLUA_METHOD TvbRange_le_int64(lua_State* L) {
         case 7:
         case 8: {
             pushInt64(L,(gint64)tvb_get_letoh64(tvbr->tvb->ws_tvb,tvbr->offset));
-            WSLUA_RETURN(1);
+            WSLUA_RETURN(1); /* The `Int64` object. */
         }
         default:
             luaL_error(L,"TvbRange:le_int64() does not handle %d byte integers",tvbr->len);
@@ -906,7 +925,8 @@ WSLUA_METHOD TvbRange_le_int64(lua_State* L) {
  *  get a Blefuscuoan float
  */
 WSLUA_METHOD TvbRange_float(lua_State* L) {
-	/* Get a Big Endian (network order) floating point number from a TvbRange. The range must be 4 or 8 octets long. */
+	/* Get a Big Endian (network order) floating point number from a `TvbRange`.
+       The range must be 4 or 8 octets long. */
     TvbRange tvbr = checkTvbRange(L,1);
     if (!(tvbr && tvbr->tvb)) return 0;
     if (tvbr->tvb->expired) {
@@ -920,7 +940,7 @@ WSLUA_METHOD TvbRange_float(lua_State* L) {
             return 1;
         case 8:
             lua_pushnumber(L,tvb_get_ntohieee_double(tvbr->tvb->ws_tvb,tvbr->offset));
-            WSLUA_RETURN(1); /* The floating point value */
+            WSLUA_RETURN(1); /* The floating point value. */
         default:
             luaL_error(L,"TvbRange:float() does not handle %d byte floating numbers",tvbr->len);
             return 0;
@@ -931,7 +951,8 @@ WSLUA_METHOD TvbRange_float(lua_State* L) {
  * get a Lilliputian float
  */
 WSLUA_METHOD TvbRange_le_float(lua_State* L) {
-	/* Get a Little Endian floating point number from a TvbRange. The range must be 4 or 8 octets long. */
+	/* Get a Little Endian floating point number from a `TvbRange`.
+       The range must be 4 or 8 octets long. */
     TvbRange tvbr = checkTvbRange(L,1);
     if (!(tvbr && tvbr->tvb)) return 0;
 
@@ -941,7 +962,7 @@ WSLUA_METHOD TvbRange_le_float(lua_State* L) {
             return 1;
         case 8:
             lua_pushnumber(L,tvb_get_letohieee_double(tvbr->tvb->ws_tvb,tvbr->offset));
-            WSLUA_RETURN(1); /* The floating point value */
+            WSLUA_RETURN(1); /* The floating point value. */
         default:
             luaL_error(L,"TvbRange:le_float() does not handle %d byte floating numbers",tvbr->len);
             return 0;
@@ -949,7 +970,7 @@ WSLUA_METHOD TvbRange_le_float(lua_State* L) {
 }
 
 WSLUA_METHOD TvbRange_ipv4(lua_State* L) {
-	/* Get an IPv4 Address from a TvbRange. */
+	/* Get an IPv4 Address from a `TvbRange`, as an `Address` object. */
     TvbRange tvbr = checkTvbRange(L,1);
     Address addr;
     guint32* ip_addr;
@@ -973,11 +994,11 @@ WSLUA_METHOD TvbRange_ipv4(lua_State* L) {
     SET_ADDRESS(addr, AT_IPv4, 4, ip_addr);
     pushAddress(L,addr);
 
-    WSLUA_RETURN(1); /* The IPv4 Address */
+    WSLUA_RETURN(1); /* The IPv4 `Address` object. */
 }
 
 WSLUA_METHOD TvbRange_le_ipv4(lua_State* L) {
-	/* Get an Little Endian IPv4 Address from a TvbRange. */
+	/* Get an Little Endian IPv4 Address from a `TvbRange`, as an `Address` object. */
     TvbRange tvbr = checkTvbRange(L,1);
     Address addr;
     guint32* ip_addr;
@@ -1002,11 +1023,11 @@ WSLUA_METHOD TvbRange_le_ipv4(lua_State* L) {
     SET_ADDRESS(addr, AT_IPv4, 4, ip_addr);
     pushAddress(L,addr);
 
-    WSLUA_RETURN(1); /* The IPv4 Address */
+    WSLUA_RETURN(1); /* The IPv4 `Address` object. */
 }
 
 WSLUA_METHOD TvbRange_ether(lua_State* L) {
-	/* Get an Ethernet Address from a TvbRange. */
+	/* Get an Ethernet Address from a `TvbRange`, as an `Address` object. */
     TvbRange tvbr = checkTvbRange(L,1);
     Address addr;
     guint8* buff;
@@ -1029,11 +1050,11 @@ WSLUA_METHOD TvbRange_ether(lua_State* L) {
     SET_ADDRESS(addr, AT_ETHER, 6, buff);
     pushAddress(L,addr);
 
-    WSLUA_RETURN(1); /* The Ethernet Address */
+    WSLUA_RETURN(1); /* The Ethernet `Address` object. */
 }
 
 WSLUA_METHOD TvbRange_nstime(lua_State* L) {
-	/* Obtain a nstime from a TvbRange */
+	/* Obtain a time_t structure from a `TvbRange`, as an `NSTime` object. */
     TvbRange tvbr = checkTvbRange(L,1);
     NSTime nstime;
 
@@ -1059,11 +1080,11 @@ WSLUA_METHOD TvbRange_nstime(lua_State* L) {
 
     pushNSTime(L, nstime);
 
-    WSLUA_RETURN(1); /* The NSTime */
+    WSLUA_RETURN(1); /* The `NSTime` object. */
 }
 
 WSLUA_METHOD TvbRange_le_nstime(lua_State* L) {
-	/* Obtain a nstime from a TvbRange */
+	/* Obtain a nstime from a `TvbRange`, as an `NSTime` object. */
     TvbRange tvbr = checkTvbRange(L,1);
     NSTime nstime;
 
@@ -1089,11 +1110,11 @@ WSLUA_METHOD TvbRange_le_nstime(lua_State* L) {
 
     pushNSTime(L, nstime);
 
-    WSLUA_RETURN(1); /* The NSTime */
+    WSLUA_RETURN(1); /* The `NSTime` object. */
 }
 
 WSLUA_METHOD TvbRange_string(lua_State* L) {
-	/* Obtain a string from a TvbRange */
+	/* Obtain a string from a `TvbRange`. */
 #define WSLUA_OPTARG_TvbRange_string_ENCODING 2 /* The encoding to use. Defaults to ENC_ASCII. */
     TvbRange tvbr = checkTvbRange(L,1);
     guint encoding = (guint)luaL_optint(L,WSLUA_OPTARG_TvbRange_string_ENCODING, ENC_ASCII|ENC_NA);
@@ -1110,7 +1131,7 @@ WSLUA_METHOD TvbRange_string(lua_State* L) {
 }
 
 static int TvbRange_ustring_any(lua_State* L, gboolean little_endian) {
-	/* Obtain a UTF-16 encoded string from a TvbRange */
+	/* Obtain a UTF-16 encoded string from a `TvbRange`. */
     TvbRange tvbr = checkTvbRange(L,1);
     gchar * str;
 
@@ -1127,17 +1148,17 @@ static int TvbRange_ustring_any(lua_State* L, gboolean little_endian) {
 }
 
 WSLUA_METHOD TvbRange_ustring(lua_State* L) {
-	/* Obtain a Big Endian (network order) UTF-16 encoded string from a TvbRange */
-    WSLUA_RETURN(TvbRange_ustring_any(L, FALSE)); /* The string */
+	/* Obtain a Big Endian (network order) UTF-16 encoded string from a `TvbRange`. */
+    WSLUA_RETURN(TvbRange_ustring_any(L, FALSE)); /* The string. */
 }
 
 WSLUA_METHOD TvbRange_le_ustring(lua_State* L) {
-	/* Obtain a Little Endian UTF-16 encoded string from a TvbRange */
-    WSLUA_RETURN(TvbRange_ustring_any(L, TRUE)); /* The string */
+	/* Obtain a Little Endian UTF-16 encoded string from a `TvbRange`. */
+    WSLUA_RETURN(TvbRange_ustring_any(L, TRUE)); /* The string. */
 }
 
 WSLUA_METHOD TvbRange_stringz(lua_State* L) {
-	/* Obtain a zero terminated string from a TvbRange */
+	/* Obtain a zero terminated string from a `TvbRange`. */
 #define WSLUA_OPTARG_TvbRange_stringz_ENCODING 2 /* The encoding to use. Defaults to ENC_ASCII. */
     TvbRange tvbr = checkTvbRange(L,1);
     guint encoding = (guint)luaL_optint(L,WSLUA_OPTARG_TvbRange_stringz_ENCODING, ENC_ASCII|ENC_NA);
@@ -1176,11 +1197,12 @@ WSLUA_METHOD TvbRange_stringz(lua_State* L) {
 
     lua_pushstring(L, (gchar*)tvb_get_stringz_enc(wmem_packet_scope(),tvbr->tvb->ws_tvb,tvbr->offset,NULL,encoding));
 
-    WSLUA_RETURN(1); /* The zero terminated string */
+    WSLUA_RETURN(1); /* The zero terminated string. */
 }
 
 WSLUA_METHOD TvbRange_strsize(lua_State* L) {
-        /* Find the size of a zero terminated string from a TvbRange.  The size of the string includes the terminating zero. */
+        /* Find the size of a zero terminated string from a `TvbRange`.
+           The size of the string includes the terminating zero. */
 #define WSLUA_OPTARG_TvbRange_strsize_ENCODING 2 /* The encoding to use. Defaults to ENC_ASCII. */
     TvbRange tvbr = checkTvbRange(L,1);
     guint encoding = (guint)luaL_optint(L,WSLUA_OPTARG_TvbRange_strsize_ENCODING, ENC_ASCII|ENC_NA);
@@ -1219,7 +1241,7 @@ WSLUA_METHOD TvbRange_strsize(lua_State* L) {
         break;
     }
 
-    WSLUA_RETURN(1); /* Length of the zero terminated string */
+    WSLUA_RETURN(1); /* Length of the zero terminated string. */
 }
 
 
@@ -1247,24 +1269,25 @@ static int TvbRange_ustringz_any(lua_State* L, gboolean little_endian) {
       offset += 2;
     } while (uchar != 0);
 
-    lua_pushstring(L, (gchar*)tvb_get_stringz_enc(wmem_packet_scope(),tvbr->tvb->ws_tvb,tvbr->offset,&count,(little_endian ? ENC_UTF_16|ENC_LITTLE_ENDIAN : ENC_UTF_16|ENC_BIG_ENDIAN)) );
+    lua_pushstring(L, (gchar*)tvb_get_stringz_enc(wmem_packet_scope(),tvbr->tvb->ws_tvb,tvbr->offset,&count,
+                                (little_endian ? ENC_UTF_16|ENC_LITTLE_ENDIAN : ENC_UTF_16|ENC_BIG_ENDIAN)) );
     lua_pushinteger(L,count);
 
     return 2; /* The zero terminated string, the length found in tvbr */
 }
 
 WSLUA_METHOD TvbRange_ustringz(lua_State* L) {
-	/* Obtain a Big Endian (network order) UTF-16 encoded zero terminated string from a TvbRange */
-    WSLUA_RETURN(TvbRange_ustringz_any(L, FALSE)); /* The zero terminated string, the length found in tvbr */
+	/* Obtain a Big Endian (network order) UTF-16 encoded zero terminated string from a `TvbRange`. */
+    WSLUA_RETURN(TvbRange_ustringz_any(L, FALSE)); /* Two return values: the zero terminated string, and the length. */
 }
 
 WSLUA_METHOD TvbRange_le_ustringz(lua_State* L) {
 	/* Obtain a Little Endian UTF-16 encoded zero terminated string from a TvbRange */
-    WSLUA_RETURN(TvbRange_ustringz_any(L, TRUE)); /* The zero terminated string, the length found in tvbr */
+    WSLUA_RETURN(TvbRange_ustringz_any(L, TRUE)); /* Two return values: the zero terminated string, and the length. */
 }
 
 WSLUA_METHOD TvbRange_bytes(lua_State* L) {
-	/* Obtain a ByteArray */
+	/* Obtain a `ByteArray` from a `TvbRange`. */
     TvbRange tvbr = checkTvbRange(L,1);
     GByteArray* ba;
 
@@ -1279,12 +1302,12 @@ WSLUA_METHOD TvbRange_bytes(lua_State* L) {
 
     pushByteArray(L,ba);
 
-    WSLUA_RETURN(1); /* The ByteArray */
+    WSLUA_RETURN(1); /* The `ByteArray` object. */
 }
 
 WSLUA_METHOD TvbRange_bitfield(lua_State* L) {
-	/* Get a bitfield from a TvbRange. */
-#define WSLUA_OPTARG_TvbRange_bitfield_POSITION 2 /* The bit offset from the beginning of the TvbRange. Defaults to 0. */
+	/* Get a bitfield from a `TvbRange`. */
+#define WSLUA_OPTARG_TvbRange_bitfield_POSITION 2 /* The bit offset from the beginning of the `TvbRange`. Defaults to 0. */
 #define WSLUA_OPTARG_TvbRange_bitfield_LENGTH 3 /* The length (in bits) of the field. Defaults to 1. */
 
     TvbRange tvbr = checkTvbRange(L,1);
@@ -1321,9 +1344,9 @@ WSLUA_METHOD TvbRange_bitfield(lua_State* L) {
 }
 
 WSLUA_METHOD TvbRange_range(lua_State* L) {
-	/* Creates a sub-TvbRange from this TvbRange. This is used also as the TvbRange:__call() metamethod. */
-#define WSLUA_OPTARG_TvbRange_range_OFFSET 2 /* The offset (in octets) from the beginning of the TvbRange. Defaults to 0. */
-#define WSLUA_OPTARG_TvbRange_range_LENGTH 3 /* The length (in octets) of the range. Defaults to until the end of the TvbRange. */
+	/* Creates a sub-`TvbRange` from this `TvbRange`. */
+#define WSLUA_OPTARG_TvbRange_range_OFFSET 2 /* The offset (in octets) from the beginning of the `TvbRange`. Defaults to 0. */
+#define WSLUA_OPTARG_TvbRange_range_LENGTH 3 /* The length (in octets) of the range. Defaults to until the end of the `TvbRange`. */
 
     TvbRange tvbr = checkTvbRange(L,1);
     int offset = luaL_optint(L,WSLUA_OPTARG_TvbRange_range_OFFSET,0);
@@ -1390,7 +1413,7 @@ static int TvbRange__gc(lua_State* L) {
 }
 
 WSLUA_METHOD TvbRange_len(lua_State* L) {
-	/* Obtain the length of a TvbRange */
+	/* Obtain the length of a `TvbRange`. */
     TvbRange tvbr = checkTvbRange(L,1);
 
     if (!(tvbr && tvbr->tvb)) return 0;
@@ -1403,7 +1426,7 @@ WSLUA_METHOD TvbRange_len(lua_State* L) {
 }
 
 WSLUA_METHOD TvbRange_offset(lua_State* L) {
-	/* Obtain the offset in a TvbRange */
+	/* Obtain the offset in a `TvbRange`. */
     TvbRange tvbr = checkTvbRange(L,1);
 
     if (!(tvbr && tvbr->tvb)) return 0;
@@ -1416,7 +1439,7 @@ WSLUA_METHOD TvbRange_offset(lua_State* L) {
 }
 
 WSLUA_METHOD TvbRange_raw(lua_State* L) {
-    /* Obtain a Lua string of the binary bytes in a TvbRange. */
+    /* Obtain a Lua string of the binary bytes in a `TvbRange`. */
 #define WSLUA_OPTARG_TvbRange_raw_OFFSET 2 /* The position of the first byte (default=0/first). */
 #define WSLUA_OPTARG_TvbRange_raw_LENGTH 3 /* The length of the segment to get (default=all). */
     TvbRange tvbr = checkTvbRange(L,1);
@@ -1447,12 +1470,12 @@ WSLUA_METHOD TvbRange_raw(lua_State* L) {
 
     lua_pushlstring(L, tvb_get_ptr(tvbr->tvb->ws_tvb, offset, len), len);
 
-    WSLUA_RETURN(1); /* A Lua string of the binary bytes in the TvbRange. */
+    WSLUA_RETURN(1); /* A Lua string of the binary bytes in the `TvbRange`. */
 }
 
 
 WSLUA_METAMETHOD TvbRange__tostring(lua_State* L) {
-	/* Converts the TvbRange into a string. As the string gets truncated
+	/* Converts the `TvbRange` into a string. As the string gets truncated
 	   you should use this only for debugging purposes
 	   or if what you want is to have a truncated string in the format 67:89:AB:... */
     TvbRange tvbr = checkTvbRange(L,1);