wslua: Update the Int64 docs.

Add content from https://wiki.wireshark.org/LuaAPI/Int64. Update as
needed.

Change-Id: I6a5f8c1cdeddee6d552fde940224704daca980b5
Reviewed-on: https://code.wireshark.org/review/36639
Reviewed-by: Gerald Combs <gerald@wireshark.org>
Petri-Dish: Gerald Combs <gerald@wireshark.org>
Tested-by: Petri Dish Buildbot
Reviewed-by: Anders Broman <a.broman58@gmail.com>

1 files changed, 183 insertions, 133 deletions

diff --git a/epan/wslua/wslua_int64.c b/epan/wslua/wslua_int64.c
index 803a09d403..da904c3cea 100644
--- a/epan/wslua/wslua_int64.c
+++ b/epan/wslua/wslua_int64.c
@@ -22,14 +22,63 @@ either expressed or implied, of the FreeBSD Project.
 
 #include "wslua.h"
 
-/* WSLUA_MODULE Int64 Handling 64-bit Integers
+    /*
+    WSLUA_MODULE Int64 Handling 64-bit Integers
 
-  Lua uses one single number representation which can be chosen at compile time and since
-  it is often set to IEEE 754 double precision floating point, one cannot store a 64 bit integer
-  with full precision.
+    Lua uses one single number representation which can be chosen at compile time and since it is often set to IEEE 754 double precision floating point, one cannot store 64 bit integers with full precision.
 
-  For details, see https://wiki.wireshark.org/LuaAPI/Int64.
- */
+    Lua numbers are stored as floating point (doubles) internally, not integers; thus while they can represent incredibly large numbers, above 2^53 they lose integral precision -- they can't represent every whole integer value.
+    For example if you set a lua variable to the number 9007199254740992 and tried to increment it by 1, you'd get the same number because it can't represent 9007199254740993 (only the even number 9007199254740994).
+
+    Therefore, in order to count higher than 2^53 in integers, we need a true integer type.
+    The way this is done is with an explicit 'Int64' or 'UInt64' object (i.e., Lua userdata).
+    This object has metamethods for all of the math and comparison operators, so you can handle it like any number variable.
+    For the math operators, it can even be mixed with plain Lua numbers.
+
+    For example 'my64num = my64num + 1' will work even if 'my64num' is a <<lua_class_Int64,`Int64`>> or <<lua_class_UInt64,`UInt64`>> object.
+    Note that comparison operators ('==','$$<=$$','>', etc.) will not work with plain numbers -- only other Int64/UInt64 objects.
+    This is a limitation of Lua itself, in terms of how it handles operator overloading.
+
+    // Previous to Wireshark release 1.11, Int64 and UInt64 could only be created by tvbrange:int64() or tvbrange:le_int64(), or tvbrange:uint64() or tvbrange:le_uint64() or tvbrange:bitfield(), and had only a couple functions (the metamethods tostring() and concat()).
+    // All of the functions on this page are only available starting in Wireshark 1.11 and higher.
+
+    [WARNING]
+    ====
+    Many of the UInt64/Int64 functions accept a Lua number as an argument.
+    You should be very careful to never use Lua numbers bigger than 32 bits (i.e., the number value 4,294,967,295 or the literal 0xFFFFFFFF) for such arguments, because Lua itself does not handle bigger numbers consistently across platforms (32-bit vs. 64-bit systems), and because a Lua number is a C-code double which cannot have more than 53 bits of precision.
+    Instead, use a Int64 or UInt64 for the argument.
+    ====
+
+    For example, do this...
+
+    [source,lua]
+    ----
+    local mynum = UInt64(0x2b89dd1e, 0x3f91df0b)
+    ----
+
+    ...instead of this:
+
+    [source,lua]
+    ----
+    -- Bad. Leads to inconsistent results across platforms
+    local mynum = UInt64(0x3f91df0b2b89dd1e)
+    ----
+
+    And do this...
+
+    [source,lua]
+    ----
+    local masked = mynum:band(UInt64(0, 0xFFFFFFFF))
+    ----
+
+    ...instead of this:
+
+    [source,lua]
+    ----
+    -- Bad. Leads to inconsistent results across platforms
+    local masked = mynum:band(0xFFFFFFFF00000000)
+    ----
+    */
 
 #define LUATYPE64_STRING_SIZE 21  /* string to hold 18446744073709551615 */
 
@@ -40,11 +89,11 @@ either expressed or implied, of the FreeBSD Project.
 #endif
 
 WSLUA_CLASS_DEFINE_BASE(Int64,NOP,0);
-/*
-  `Int64` represents a 64 bit signed integer.
+    /*
+    <<lua_class_Int64,`Int64`>> represents a 64 bit signed integer.
 
-  For details, see https://wiki.wireshark.org/LuaAPI/Int64.
- */
+    Note the caveats <<lua_module_Int64,listed above>>.
+    */
 
 /* A checkInt64 but that also auto-converts numbers, strings, and UINT64 to a gint64 */
 static gint64 getInt64(lua_State *L, int i)
@@ -91,11 +140,11 @@ void Int64_pack(lua_State* L, luaL_Buffer *b, gint idx, gboolean asLittleEndian)
 }
 
 WSLUA_METHOD Int64_encode(lua_State* L) {
-    /* Encodes the `Int64` number into an 8-byte Lua string, using given endianness.
+    /* Encodes the <<lua_class_Int64,`Int64`>> number into an 8-byte Lua string using the given endianness.
        @since 1.11.3
      */
 #define WSLUA_OPTARG_Int64_encode_ENDIAN 2 /* If set to true then little-endian is used,
-                                              if false then big-endian; if missing/nil,
+                                              if false then big-endian; if missing or `nil`,
                                               native host endian. */
     luaL_Buffer b;
     gboolean asLittleEndian = IS_LITTLE_ENDIAN;
@@ -136,12 +185,12 @@ int Int64_unpack(lua_State* L, const gchar *buff, gboolean asLittleEndian) {
 }
 
 WSLUA_CONSTRUCTOR Int64_decode(lua_State* L) {
-    /* Decodes an 8-byte Lua string, using given endianness, into a new `Int64` object.
+    /* Decodes an 8-byte Lua string, using the given endianness, into a new <<lua_class_Int64,`Int64`>> object.
        @since 1.11.3
      */
 #define WSLUA_ARG_Int64_decode_STRING 1 /* The Lua string containing a binary 64-bit integer. */
 #define WSLUA_OPTARG_Int64_decode_ENDIAN 2 /* If set to true then little-endian is used,
-                                              if false then big-endian; if missing/nil, native
+                                              if false then big-endian; if missing or `nil`, native
                                               host endian. */
     gboolean asLittleEndian = IS_LITTLE_ENDIAN;
     size_t len = 0;
@@ -158,18 +207,18 @@ WSLUA_CONSTRUCTOR Int64_decode(lua_State* L) {
         lua_pushnil(L);
     }
 
-    WSLUA_RETURN(1); /* The `Int64` object created, or nil on failure. */
+    WSLUA_RETURN(1); /* The <<lua_class_Int64,`Int64`>> object created, or nil on failure. */
 }
 
 WSLUA_CONSTRUCTOR Int64_new(lua_State* L) {
-    /* Creates a `Int64` Object.
+    /* Creates a <<lua_class_Int64,`Int64`>> Object.
        @since 1.11.3
      */
-#define WSLUA_OPTARG_Int64_new_VALUE 1 /* A number, `UInt64`, `Int64`, or string of ASCII digits
-                                          to assign the value of the new `Int64` (default=0). */
+#define WSLUA_OPTARG_Int64_new_VALUE 1 /* A number, <<lua_class_UInt64,`UInt64`>>, <<lua_class_Int64,`Int64`>>, or string of ASCII digits
+                                          to assign the value of the new <<lua_class_Int64,`Int64`>>. Default is 0. */
 #define WSLUA_OPTARG_Int64_new_HIGHVALUE 2 /* If this is a number and the first argument was
                                               a number, then the first will be treated as a
-                                              lower 32-bits, and this is the high-order 32
+                                              lower 32 bits, and this is the high-order 32
                                               bit number. */
     gint64 value = 0;
 
@@ -197,36 +246,36 @@ WSLUA_CONSTRUCTOR Int64_new(lua_State* L) {
 
     pushInt64(L,value);
 
-    WSLUA_RETURN(1); /* The new `Int64` object. */
+    WSLUA_RETURN(1); /* The new <<lua_class_Int64,`Int64`>> object. */
 }
 
 WSLUA_METAMETHOD Int64__call(lua_State* L) {
-    /* Creates a `Int64` Object.
+    /* Creates a <<lua_class_Int64,`Int64`>> object.
        @since 1.11.3
      */
     lua_remove(L,1); /* remove the table */
-    WSLUA_RETURN(Int64_new(L)); /* The new `Int64` object. */
+    WSLUA_RETURN(Int64_new(L)); /* The new <<lua_class_Int64,`Int64`>> object. */
 }
 
 WSLUA_CONSTRUCTOR Int64_max(lua_State* L) {
-    /* Gets the max possible value.
+    /* Creates an <<lua_class_Int64,`Int64`>> of the maximum possible positive value. In other words, this should return an Int64 object of the number 9,223,372,036,854,775,807.
        @since 1.11.3
      */
     pushInt64(L, G_MAXINT64);
-    WSLUA_RETURN(1); /* The new `Int64` object of the max value. */
+    WSLUA_RETURN(1); /* The new <<lua_class_Int64,`Int64`>> object of the maximum value. */
 }
 
 WSLUA_CONSTRUCTOR Int64_min(lua_State* L) {
-    /* Gets the min possible value.
+    /* Creates an <<lua_class_Int64,`Int64`>> of the minimum possible negative value. In other words, this should return an Int64 object of the number -9,223,372,036,854,775,808.
        @since 1.11.3
      */
     pushInt64(L, G_MININT64);
-    WSLUA_RETURN(1); /* The new `Int64` object of the min value. */
+    WSLUA_RETURN(1); /* The new <<lua_class_Int64,`Int64`>> object of the minimum value. */
 }
 
 
 WSLUA_METHOD Int64_tonumber(lua_State* L) {
-    /* Returns a Lua number of the `Int64` value - this may lose precision.
+    /* Returns a Lua number of the <<lua_class_Int64,`Int64`>> value. Note that this may lose precision.
        @since 1.11.3
      */
     lua_pushnumber(L, (lua_Number)(checkInt64(L,1)));
@@ -234,10 +283,10 @@ WSLUA_METHOD Int64_tonumber(lua_State* L) {
 }
 
 WSLUA_CONSTRUCTOR Int64_fromhex(lua_State* L) {
-    /* Creates an `Int64` object from the given hex string.
+    /* Creates an <<lua_class_Int64,`Int64`>> object from the given hexadecimal string.
        @since 1.11.3
      */
-#define WSLUA_ARG_Int64_fromhex_HEX 1 /* The hex-ascii Lua string. */
+#define WSLUA_ARG_Int64_fromhex_HEX 1 /* The hex-ASCII Lua string. */
     guint64 result = 0;
     size_t len = 0;
     const gchar *s = luaL_checklstring(L,WSLUA_ARG_Int64_fromhex_HEX,&len);
@@ -248,15 +297,15 @@ WSLUA_CONSTRUCTOR Int64_fromhex(lua_State* L) {
         }
     }
     pushInt64(L,(gint64)result);
-    WSLUA_RETURN(1); /* The new `Int64` object. */
+    WSLUA_RETURN(1); /* The new <<lua_class_Int64,`Int64`>> object. */
 }
 
 WSLUA_METHOD Int64_tohex(lua_State* L) {
-    /* Returns a hex string of the `Int64` value.
+    /* Returns a hexadecimal string of the <<lua_class_Int64,`Int64`>> value.
        @since 1.11.3
      */
-#define WSLUA_OPTARG_Int64_new_NUMBYTES 2 /* The number of hex-chars/nibbles to generate,
-                                             negative means uppercase (default=16). */
+#define WSLUA_OPTARG_Int64_new_NUMBYTES 2 /* The number of hex chars/nibbles to generate.
+                                             A negative value generates uppercase. Default is 16. */
     gint64 b = getInt64(L,1);
     lua_Integer n = luaL_optinteger(L, WSLUA_OPTARG_Int64_new_NUMBYTES, 16);
     const gchar *hexdigits = "0123456789abcdef";
@@ -270,8 +319,8 @@ WSLUA_METHOD Int64_tohex(lua_State* L) {
 }
 
 WSLUA_METHOD Int64_higher(lua_State* L) {
-    /* Returns a Lua number of the higher 32-bits of the `Int64` value. (negative `Int64`
-       will return a negative Lua number).
+    /* Returns a Lua number of the higher 32 bits of the <<lua_class_Int64,`Int64`>> value. A negative <<lua_class_Int64,`Int64`>>
+       will return a negative Lua number.
        @since 1.11.3
      */
     gint64 num = getInt64(L,1);
@@ -287,7 +336,7 @@ WSLUA_METHOD Int64_higher(lua_State* L) {
 }
 
 WSLUA_METHOD Int64_lower(lua_State* L) {
-    /* Returns a Lua number of the lower 32-bits of the `Int64` value. (always positive).
+    /* Returns a Lua number of the lower 32 bits of the <<lua_class_Int64,`Int64`>> value. This will always be positive.
        @since 1.11.3
      */
     gint64 b = getInt64(L,1);
@@ -297,7 +346,7 @@ WSLUA_METHOD Int64_lower(lua_State* L) {
 }
 
 WSLUA_METAMETHOD Int64__tostring(lua_State* L) {
-    /* Converts the `Int64` into a string of decimal digits. */
+    /* Converts the <<lua_class_Int64,`Int64`>> into a string of decimal digits. */
     gint64 num = getInt64(L,1);
     gchar s[LUATYPE64_STRING_SIZE];
     if (g_snprintf(s, LUATYPE64_STRING_SIZE, "%" G_GINT64_MODIFIER "d", num) < 0) {
@@ -308,11 +357,11 @@ WSLUA_METAMETHOD Int64__tostring(lua_State* L) {
 }
 
 WSLUA_METAMETHOD Int64__unm(lua_State* L) {
-    /* Returns the negative of the `Int64`, in a new `Int64`.
+    /* Returns the negative of the <<lua_class_Int64,`Int64`>> as a new <<lua_class_Int64,`Int64`>>.
        @since 1.11.3
      */
     pushInt64(L,-(getInt64(L,1)));
-    WSLUA_RETURN(1); /* The new `Int64`. */
+    WSLUA_RETURN(1); /* The new <<lua_class_Int64,`Int64`>>. */
 }
 
 #define WSLUA_MATH_OP_FUNC(obj,op) \
@@ -323,28 +372,28 @@ WSLUA_METAMETHOD Int64__unm(lua_State* L) {
     return 1
 
 WSLUA_METAMETHOD Int64__add(lua_State* L) {
-    /* Adds two `Int64` together and returns a new one (this may wrap the value).
+    /* Adds two <<lua_class_Int64,`Int64`>> together and returns a new one. The value may wrapped.
        @since 1.11.3
      */
     WSLUA_MATH_OP_FUNC(Int64,+);
 }
 
 WSLUA_METAMETHOD Int64__sub(lua_State* L) {
-    /* Subtracts two `Int64` and returns a new one (this may wrap the value).
+    /* Subtracts two <<lua_class_Int64,`Int64`>> and returns a new one. The value may wrapped.
        @since 1.11.3
      */
     WSLUA_MATH_OP_FUNC(Int64,-);
 }
 
 WSLUA_METAMETHOD Int64__mul(lua_State* L) {
-    /* Multiplies two `Int64` and returns a new one (this may truncate the value).
+    /* Multiplies two <<lua_class_Int64,`Int64`>> and returns a new one. The value may truncated.
        @since 1.11.3
      */
     WSLUA_MATH_OP_FUNC(Int64,*);
 }
 
 WSLUA_METAMETHOD Int64__div(lua_State* L) {
-    /* Divides two `Int64` and returns a new one (integer divide, no remainder).
+    /* Divides two <<lua_class_Int64,`Int64`>> and returns a new one. Integer divide, no remainder.
        Trying to divide by zero results in a Lua error.
        @since 1.11.3
      */
@@ -354,11 +403,11 @@ WSLUA_METAMETHOD Int64__div(lua_State* L) {
         return luaL_error(L, "Trying to divide Int64 by zero");
     }
     pushInt64(L, num1 / num2);
-    WSLUA_RETURN(1); /* The `Int64` object. */
+    WSLUA_RETURN(1); /* The <<lua_class_Int64,`Int64`>> object. */
 }
 
 WSLUA_METAMETHOD Int64__mod(lua_State* L) {
-    /* Divides two `Int64` and returns a new one of the remainder.
+    /* Divides two <<lua_class_Int64,`Int64`>> and returns a new one of the remainder.
        Trying to modulo by zero results in a Lua error.
        @since 1.11.3
      */
@@ -368,12 +417,12 @@ WSLUA_METAMETHOD Int64__mod(lua_State* L) {
         return luaL_error(L, "Trying to modulo Int64 by zero");
     }
     pushInt64(L, num1 % num2);
-    WSLUA_RETURN(1); /* The `Int64` object. */
+    WSLUA_RETURN(1); /* The <<lua_class_Int64,`Int64`>> object. */
 }
 
 WSLUA_METAMETHOD Int64__pow(lua_State* L) {
-    /* The first `Int64` is taken to the power of the second `Int64`, returning a new
-       one (this may truncate the value).
+    /* The first <<lua_class_Int64,`Int64`>> is taken to the power of the second <<lua_class_Int64,`Int64`>>, returning a new
+       one. This may truncate the value.
        @since 1.11.3
      */
     gint64 num1 = getInt64(L,1);
@@ -389,7 +438,7 @@ WSLUA_METAMETHOD Int64__pow(lua_State* L) {
         }
     }
     pushInt64(L,result);
-    WSLUA_RETURN(1); /* The `Int64` object. */
+    WSLUA_RETURN(1); /* The <<lua_class_Int64,`Int64`>> object. */
 }
 
 #define WSLUA_COMP_OP_FUNC(obj,op) \
@@ -399,32 +448,32 @@ WSLUA_METAMETHOD Int64__pow(lua_State* L) {
     return 1
 
 WSLUA_METAMETHOD Int64__eq(lua_State* L) {
-    /* Returns true if both `Int64` are equal.
+    /* Returns `true` if both <<lua_class_Int64,`Int64`>> are equal.
        @since 1.11.3
      */
     WSLUA_COMP_OP_FUNC(Int64,==);
 }
 
 WSLUA_METAMETHOD Int64__lt(lua_State* L) {
-    /* Returns true if first `Int64` < second.
+    /* Returns `true` if first <<lua_class_Int64,`Int64`>> is less than the second.
        @since 1.11.3
      */
     WSLUA_COMP_OP_FUNC(Int64,<);
 }
 
 WSLUA_METAMETHOD Int64__le(lua_State* L) {
-    /* Returns true if first `Int64` <= second.
+    /* Returns `true` if the first <<lua_class_Int64,`Int64`>> is less than or equal to the second.
        @since 1.11.3
      */
     WSLUA_COMP_OP_FUNC(Int64,<=);
 }
 
 WSLUA_METHOD Int64_bnot(lua_State* L) {
-    /* Returns a `Int64` of the bitwise 'not' operation.
+    /* Returns a <<lua_class_Int64,`Int64`>> of the bitwise 'not' operation.
        @since 1.11.3
      */
     pushInt64(L,~(getInt64(L,1)));
-    WSLUA_RETURN(1); /* The `Int64` object. */
+    WSLUA_RETURN(1); /* The <<lua_class_Int64,`Int64`>> object. */
 }
 
 #define WSLUA_BIT_OP_FUNC(obj,op) \
@@ -437,7 +486,7 @@ WSLUA_METHOD Int64_bnot(lua_State* L) {
     return 1
 
 WSLUA_METHOD Int64_band(lua_State* L) {
-    /* Returns a `Int64` of the bitwise 'and' operation, with the given number/`Int64`/`UInt64`.
+    /* Returns a <<lua_class_Int64,`Int64`>> of the bitwise 'and' operation with the given number/`Int64`/`UInt64`.
        Note that multiple arguments are allowed.
        @since 1.11.3
      */
@@ -445,7 +494,7 @@ WSLUA_METHOD Int64_band(lua_State* L) {
 }
 
 WSLUA_METHOD Int64_bor(lua_State* L) {
-    /* Returns a `Int64` of the bitwise 'or' operation, with the given number/`Int64`/`UInt64`.
+    /* Returns a <<lua_class_Int64,`Int64`>> of the bitwise 'or' operation, with the given number/`Int64`/`UInt64`.
        Note that multiple arguments are allowed.
        @since 1.11.3
      */
@@ -453,7 +502,7 @@ WSLUA_METHOD Int64_bor(lua_State* L) {
 }
 
 WSLUA_METHOD Int64_bxor(lua_State* L) {
-    /* Returns a `Int64` of the bitwise 'xor' operation, with the given number/`Int64`/`UInt64`.
+    /* Returns a <<lua_class_Int64,`Int64`>> of the bitwise 'xor' operation, with the given number/`Int64`/`UInt64`.
        Note that multiple arguments are allowed.
        @since 1.11.3
      */
@@ -461,7 +510,7 @@ WSLUA_METHOD Int64_bxor(lua_State* L) {
 }
 
 WSLUA_METHOD Int64_lshift(lua_State* L) {
-    /* Returns a `Int64` of the bitwise logical left-shift operation, by the given
+    /* Returns a <<lua_class_Int64,`Int64`>> of the bitwise logical left-shift operation, by the given
        number of bits.
        @since 1.11.3
      */
@@ -469,11 +518,11 @@ WSLUA_METHOD Int64_lshift(lua_State* L) {
     guint64 b = (guint64) getInt64(L,1);
     guint32 n = wslua_checkguint32(L,WSLUA_ARG_Int64_lshift_NUMBITS);
     pushInt64(L,(gint64)(b << n));
-    WSLUA_RETURN(1); /* The `Int64` object. */
+    WSLUA_RETURN(1); /* The <<lua_class_Int64,`Int64`>> object. */
 }
 
 WSLUA_METHOD Int64_rshift(lua_State* L) {
-    /* Returns a `Int64` of the bitwise logical right-shift operation, by the
+    /* Returns a <<lua_class_Int64,`Int64`>> of the bitwise logical right-shift operation, by the
        given number of bits.
        @since 1.11.3
      */
@@ -481,11 +530,11 @@ WSLUA_METHOD Int64_rshift(lua_State* L) {
     guint64 b = (guint64) getInt64(L,1);
     guint32 n = wslua_checkguint32(L,WSLUA_ARG_Int64_rshift_NUMBITS);
     pushInt64(L,(gint64)(b >> n));
-    WSLUA_RETURN(1); /* The `Int64` object. */
+    WSLUA_RETURN(1); /* The <<lua_class_Int64,`Int64`>> object. */
 }
 
 WSLUA_METHOD Int64_arshift(lua_State* L) {
-    /* Returns a `Int64` of the bitwise arithmetic right-shift operation, by the
+    /* Returns a <<lua_class_Int64,`Int64`>> of the bitwise arithmetic right-shift operation, by the
        given number of bits.
        @since 1.11.3
      */
@@ -493,11 +542,11 @@ WSLUA_METHOD Int64_arshift(lua_State* L) {
     gint64 b = getInt64(L,1);
     gint32 n = wslua_checkgint32(L,WSLUA_ARG_Int64_arshift_NUMBITS);
     pushInt64(L,(b >> n));
-    WSLUA_RETURN(1); /* The `Int64` object. */
+    WSLUA_RETURN(1); /* The <<lua_class_Int64,`Int64`>> object. */
 }
 
 WSLUA_METHOD Int64_rol(lua_State* L) {
-    /* Returns a `Int64` of the bitwise left rotation operation, by the given number of
+    /* Returns a <<lua_class_Int64,`Int64`>> of the bitwise left rotation operation, by the given number of
        bits (up to 63).
        @since 1.11.3
      */
@@ -505,11 +554,11 @@ WSLUA_METHOD Int64_rol(lua_State* L) {
     guint64 b = (guint64) getInt64(L,1);
     guint32 n = wslua_checkguint32(L,WSLUA_ARG_Int64_rol_NUMBITS);
     pushInt64(L,(gint64)((b << n) | (b >> (64-n))));
-    WSLUA_RETURN(1); /* The `Int64` object. */
+    WSLUA_RETURN(1); /* The <<lua_class_Int64,`Int64`>> object. */
 }
 
 WSLUA_METHOD Int64_ror(lua_State* L) {
-    /* Returns a `Int64` of the bitwise right rotation operation, by the given number of
+    /* Returns a <<lua_class_Int64,`Int64`>> of the bitwise right rotation operation, by the given number of
        bits (up to 63).
        @since 1.11.3
      */
@@ -517,11 +566,11 @@ WSLUA_METHOD Int64_ror(lua_State* L) {
     guint64 b = (guint64) getInt64(L,1);
     guint32 n = wslua_checkguint32(L,WSLUA_ARG_Int64_ror_NUMBITS);
     pushInt64(L,(gint64)((b << (64-n)) | (b >> n)));
-    WSLUA_RETURN(1); /* The `Int64` object. */
+    WSLUA_RETURN(1); /* The <<lua_class_Int64,`Int64`>> object. */
 }
 
 WSLUA_METHOD Int64_bswap(lua_State* L) {
-    /* Returns a `Int64` of the bytes swapped. This can be used to convert little-endian
+    /* Returns a <<lua_class_Int64,`Int64`>> of the bytes swapped. This can be used to convert little-endian
        64-bit numbers to big-endian 64 bit numbers or vice versa.
        @since 1.11.3
      */
@@ -534,7 +583,7 @@ WSLUA_METHOD Int64_bswap(lua_State* L) {
         b >>= 8;
     }
     pushInt64(L,(gint64)result);
-    WSLUA_RETURN(1); /* The `Int64` object. */
+    WSLUA_RETURN(1); /* The <<lua_class_Int64,`Int64`>> object. */
 }
 
 /* Gets registered as metamethod automatically by WSLUA_REGISTER_CLASS/META. */
@@ -591,12 +640,13 @@ LUALIB_API int Int64_register(lua_State* L) {
 
 
 WSLUA_CLASS_DEFINE_BASE(UInt64,NOP,0);
-/* `UInt64` represents a 64 bit unsigned integer, similar to `Int64`.
+    /*
+    <<lua_class_UInt64,`UInt64`>> represents a 64 bit unsigned integer, similar to <<lua_class_Int64,`Int64`>>.
 
-   For details, see: https://wiki.wireshark.org/LuaAPI/Int64.
-*/
+    Note the caveats <<lua_module_Int64,listed above>>.
+    */
 
-/* A checkUInt64 but that also auto-converts numbers, strings, and `Int64` to a guint64. */
+/* A checkUInt64 but that also auto-converts numbers, strings, and <<lua_class_Int64,`Int64`>> to a guint64. */
 static guint64 getUInt64(lua_State *L, int i)
 {
     gchar *end = NULL;
@@ -617,7 +667,7 @@ static guint64 getUInt64(lua_State *L, int i)
         }
 }
 
-/* Encodes `UInt64` userdata into Lua string struct with given endianness */
+/* Encodes <<lua_class_UInt64,`UInt64`>> userdata into Lua string struct with given endianness */
 void UInt64_pack(lua_State* L, luaL_Buffer *b, gint idx, gboolean asLittleEndian) {
     guint64 value = checkUInt64(L,idx);
     gint8 buff[sizeof(guint64)];
@@ -640,11 +690,11 @@ void UInt64_pack(lua_State* L, luaL_Buffer *b, gint idx, gboolean asLittleEndian
 }
 
 WSLUA_METHOD UInt64_encode(lua_State* L) {
-    /* Encodes the `UInt64` number into an 8-byte Lua binary string, using given endianness.
+    /* Encodes the <<lua_class_UInt64,`UInt64`>> number into an 8-byte Lua binary string, using given endianness.
        @since 1.11.3
      */
 #define WSLUA_OPTARG_UInt64_encode_ENDIAN 2 /* If set to true then little-endian is used,
-                                               if false then big-endian; if missing/nil,
+                                               if false then big-endian; if missing or `nil`,
                                                native host endian. */
     luaL_Buffer b;
     gboolean asLittleEndian = IS_LITTLE_ENDIAN;
@@ -662,7 +712,7 @@ WSLUA_METHOD UInt64_encode(lua_State* L) {
     WSLUA_RETURN(1); /* The Lua binary string. */
 }
 
-/* Decodes from string buffer struct into `UInt64` userdata, with given endianness. */
+/* Decodes from string buffer struct into <<lua_class_UInt64,`UInt64`>> userdata, with given endianness. */
 int UInt64_unpack(lua_State* L, const gchar *buff, gboolean asLittleEndian) {
     guint64 value = 0;
     gint i;
@@ -685,12 +735,12 @@ int UInt64_unpack(lua_State* L, const gchar *buff, gboolean asLittleEndian) {
 }
 
 WSLUA_CONSTRUCTOR UInt64_decode(lua_State* L) {
-    /* Decodes an 8-byte Lua binary string, using given endianness, into a new `UInt64` object.
+    /* Decodes an 8-byte Lua binary string, using given endianness, into a new <<lua_class_UInt64,`UInt64`>> object.
        @since 1.11.3
      */
 #define WSLUA_ARG_UInt64_decode_STRING 1 /* The Lua string containing a binary 64-bit integer. */
 #define WSLUA_OPTARG_UInt64_decode_ENDIAN 2 /* If set to true then little-endian is used,
-                                               if false then big-endian; if missing/nil,
+                                               if false then big-endian; if missing or `nil`,
                                                native host endian. */
     gboolean asLittleEndian = IS_LITTLE_ENDIAN;
     size_t len = 0;
@@ -707,18 +757,18 @@ WSLUA_CONSTRUCTOR UInt64_decode(lua_State* L) {
         lua_pushnil(L);
     }
 
-    WSLUA_RETURN(1); /* The `UInt64` object created, or nil on failure. */
+    WSLUA_RETURN(1); /* The <<lua_class_UInt64,`UInt64`>> object created, or nil on failure. */
 }
 
 WSLUA_CONSTRUCTOR UInt64_new(lua_State* L) {
-    /* Creates a `UInt64` Object.
+    /* Creates a <<lua_class_UInt64,`UInt64`>> Object.
        @since 1.11.3
      */
-#define WSLUA_OPTARG_UInt64_new_VALUE 1 /* A number, `UInt64`, `Int64`, or string of digits
-                                           to assign the value of the new `UInt64` (default=0). */
+#define WSLUA_OPTARG_UInt64_new_VALUE 1 /* A number, <<lua_class_UInt64,`UInt64`>>, <<lua_class_Int64,`Int64`>>, or string of digits
+                                           to assign the value of the new <<lua_class_UInt64,`UInt64`>>. Default is 0. */
 #define WSLUA_OPTARG_UInt64_new_HIGHVALUE 2 /* If this is a number and the first argument was
                                                a number, then the first will be treated as a
-                                               lower 32-bits, and this is the high-order
+                                               lower 32 bits, and this is the high-order
                                                32-bit number. */
     guint64 value = 0;
 
@@ -746,35 +796,35 @@ WSLUA_CONSTRUCTOR UInt64_new(lua_State* L) {
 
     pushUInt64(L,value);
 
-    WSLUA_RETURN(1); /* The new `UInt64` object. */
+    WSLUA_RETURN(1); /* The new <<lua_class_UInt64,`UInt64`>> object. */
 }
 
 WSLUA_METAMETHOD UInt64__call(lua_State* L) {
-    /* Creates a `UInt64` Object.
+    /* Creates a <<lua_class_UInt64,`UInt64`>> object.
        @since 1.11.3
      */
     lua_remove(L,1); /* remove the table */
-    WSLUA_RETURN(UInt64_new(L)); /* The new `UInt64` object. */
+    WSLUA_RETURN(UInt64_new(L)); /* The new <<lua_class_UInt64,`UInt64`>> object. */
 }
 
 WSLUA_CONSTRUCTOR UInt64_max(lua_State* L) {
-    /* Gets the max possible value.
+    /* Creates a <<lua_class_UInt64,`UInt64`>> of the maximum possible value. In other words, this should return an UInt64 object of the number 18,446,744,073,709,551,615.
        @since 1.11.3
      */
     pushUInt64(L,G_MAXUINT64);
-    WSLUA_RETURN(1); /* The max value. */
+    WSLUA_RETURN(1); /* The maximum value. */
 }
 
 WSLUA_CONSTRUCTOR UInt64_min(lua_State* L) {
-    /* Gets the min possible value (i.e., 0).
+    /* Creates a <<lua_class_UInt64,`UInt64`>> of the minimum possible value. In other words, this should return an UInt64 object of the number 0.
        @since 1.11.3
      */
     pushUInt64(L,0);
-    WSLUA_RETURN(1); /* The min value. */
+    WSLUA_RETURN(1); /* The minimum value. */
 }
 
 WSLUA_METHOD UInt64_tonumber(lua_State* L) {
-    /* Returns a Lua number of the `UInt64` value - this may lose precision.
+    /* Returns a Lua number of the <<lua_class_UInt64,`UInt64`>> value. This may lose precision.
        @since 1.11.3
      */
     lua_pushnumber(L,(lua_Number)(checkUInt64(L,1)));
@@ -782,7 +832,7 @@ WSLUA_METHOD UInt64_tonumber(lua_State* L) {
 }
 
 WSLUA_METAMETHOD UInt64__tostring(lua_State* L) {
-    /* Converts the `UInt64` into a string. */
+    /* Converts the <<lua_class_UInt64,`UInt64`>> into a string. */
     guint64 num = getUInt64(L,1);
     gchar s[LUATYPE64_STRING_SIZE];
     if (g_snprintf(s, LUATYPE64_STRING_SIZE, "%" G_GINT64_MODIFIER "u",(guint64)num) < 0) {
@@ -793,10 +843,10 @@ WSLUA_METAMETHOD UInt64__tostring(lua_State* L) {
 }
 
 WSLUA_CONSTRUCTOR UInt64_fromhex(lua_State* L) {
-    /* Creates a `UInt64` object from the given hex string.
+    /* Creates a <<lua_class_UInt64,`UInt64`>> object from the given hex string.
        @since 1.11.3
      */
-#define WSLUA_ARG_UInt64_fromhex_HEX 1 /* The hex-ascii Lua string. */
+#define WSLUA_ARG_UInt64_fromhex_HEX 1 /* The hex-ASCII Lua string. */
     guint64 result = 0;
     size_t len = 0;
     const gchar *s = luaL_checklstring(L,WSLUA_ARG_UInt64_fromhex_HEX,&len);
@@ -807,15 +857,15 @@ WSLUA_CONSTRUCTOR UInt64_fromhex(lua_State* L) {
         }
     }
     pushUInt64(L,result);
-    WSLUA_RETURN(1); /* The new `UInt64` object. */
+    WSLUA_RETURN(1); /* The new <<lua_class_UInt64,`UInt64`>> object. */
 }
 
 WSLUA_METHOD UInt64_tohex(lua_State* L) {
-    /* Returns a hex string of the `UInt64` value.
+    /* Returns a hex string of the <<lua_class_UInt64,`UInt64`>> value.
        @since 1.11.3
      */
-#define WSLUA_OPTARG_UInt64_new_NUMBYTES 2 /* The number of hex-chars/nibbles to generate,
-                                              negative means uppercase (default=16). */
+#define WSLUA_OPTARG_UInt64_new_NUMBYTES 2 /* The number of hex-chars/nibbles to generate.
+                                              Negative means uppercase Default is 16. */
     guint64 b = getUInt64(L,1);
     lua_Integer n = luaL_optinteger(L, WSLUA_OPTARG_UInt64_new_NUMBYTES, 16);
     const gchar *hexdigits = "0123456789abcdef";
@@ -829,7 +879,7 @@ WSLUA_METHOD UInt64_tohex(lua_State* L) {
 }
 
 WSLUA_METHOD UInt64_higher(lua_State* L) {
-    /* Returns a Lua number of the higher 32-bits of the `UInt64` value. */
+    /* Returns a Lua number of the higher 32 bits of the <<lua_class_UInt64,`UInt64`>> value. */
     guint64 num = getUInt64(L,1);
     guint64 b = num;
     lua_Number n = 0;
@@ -841,43 +891,43 @@ WSLUA_METHOD UInt64_higher(lua_State* L) {
 }
 
 WSLUA_METHOD UInt64_lower(lua_State* L) {
-    /* Returns a Lua number of the lower 32-bits of the `UInt64` value. */
+    /* Returns a Lua number of the lower 32 bits of the <<lua_class_UInt64,`UInt64`>> value. */
     guint64 b = getUInt64(L,1);
     lua_pushnumber(L,(guint32)(b & G_GUINT64_CONSTANT(0x00000000FFFFFFFFF)));
     WSLUA_RETURN(1); /* The Lua number. */
 }
 
 WSLUA_METAMETHOD UInt64__unm(lua_State* L) {
-    /* Returns the `UInt64`, in a new `UInt64`, since unsigned integers can't be negated.
+    /* Returns the <<lua_class_UInt64,`UInt64`>> in a new <<lua_class_UInt64,`UInt64`>>, since unsigned integers can't be negated.
        @since 1.11.3
      */
     pushUInt64(L,getUInt64(L,1));
-    WSLUA_RETURN(1); /* The `UInt64` object. */
+    WSLUA_RETURN(1); /* The <<lua_class_UInt64,`UInt64`>> object. */
 }
 
 WSLUA_METAMETHOD UInt64__add(lua_State* L) {
-    /* Adds two `UInt64` together and returns a new one (this may wrap the value).
+    /* Adds two <<lua_class_UInt64,`UInt64`>> together and returns a new one. This may wrap the value.
        @since 1.11.3
      */
     WSLUA_MATH_OP_FUNC(UInt64,+);
 }
 
 WSLUA_METAMETHOD UInt64__sub(lua_State* L) {
-    /* Subtracts two `UInt64` and returns a new one (this may wrap the value).
+    /* Subtracts two <<lua_class_UInt64,`UInt64`>> and returns a new one. This may wrap the value.
        @since 1.11.3
      */
     WSLUA_MATH_OP_FUNC(UInt64,-);
 }
 
 WSLUA_METAMETHOD UInt64__mul(lua_State* L) {
-    /* Multiplies two `UInt64` and returns a new one (this may truncate the value).
+    /* Multiplies two <<lua_class_UInt64,`UInt64`>> and returns a new one. This may truncate the value.
        @since 1.11.3
      */
     WSLUA_MATH_OP_FUNC(UInt64,*);
 }
 
 WSLUA_METAMETHOD UInt64__div(lua_State* L) {
-    /* Divides two `UInt64` and returns a new one (integer divide, no remainder).
+    /* Divides two <<lua_class_UInt64,`UInt64`>> and returns a new one. Integer divide, no remainder.
        Trying to divide by zero results in a Lua error.
        @since 1.11.3
      */
@@ -887,11 +937,11 @@ WSLUA_METAMETHOD UInt64__div(lua_State* L) {
         return luaL_error(L, "Trying to divide UInt64 by zero");
     }
     pushUInt64(L, num1 / num2);
-    WSLUA_RETURN(1); /* The `UInt64` result. */
+    WSLUA_RETURN(1); /* The <<lua_class_UInt64,`UInt64`>> result. */
 }
 
 WSLUA_METAMETHOD UInt64__mod(lua_State* L) {
-    /* Divides two `UInt64` and returns a new one of the remainder.
+    /* Divides two <<lua_class_UInt64,`UInt64`>> and returns a new one of the remainder.
        Trying to modulo by zero results in a Lua error.
        @since 1.11.3
      */
@@ -901,12 +951,12 @@ WSLUA_METAMETHOD UInt64__mod(lua_State* L) {
         return luaL_error(L, "Trying to modulo UInt64 by zero");
     }
     pushUInt64(L, num1 % num2);
-    WSLUA_RETURN(1); /* The `UInt64` result. */
+    WSLUA_RETURN(1); /* The <<lua_class_UInt64,`UInt64`>> result. */
 }
 
 WSLUA_METAMETHOD UInt64__pow(lua_State* L) {
-    /* The first `UInt64` is taken to the power of the second `UInt64`/number,
-       returning a new one (this may truncate the value).
+    /* The first <<lua_class_UInt64,`UInt64`>> is taken to the power of the second <<lua_class_UInt64,`UInt64`>>/number,
+       returning a new one. This may truncate the value.
        @since 1.11.3
      */
     guint64 num1 = getUInt64(L,1);
@@ -922,40 +972,40 @@ WSLUA_METAMETHOD UInt64__pow(lua_State* L) {
         }
     }
     pushUInt64(L,result);
-    WSLUA_RETURN(1); /* The `UInt64` object. */
+    WSLUA_RETURN(1); /* The <<lua_class_UInt64,`UInt64`>> object. */
 }
 
 WSLUA_METAMETHOD UInt64__eq(lua_State* L) {
-    /* Returns true if both `UInt64` are equal.
+    /* Returns true if both <<lua_class_UInt64,`UInt64`>> are equal.
        @since 1.11.3
      */
     WSLUA_COMP_OP_FUNC(UInt64,==);
 }
 
 WSLUA_METAMETHOD UInt64__lt(lua_State* L) {
-    /* Returns true if first `UInt64` < second.
+    /* Returns true if first <<lua_class_UInt64,`UInt64`>> is less than the second.
        @since 1.11.3
      */
     WSLUA_COMP_OP_FUNC(UInt64,<);
 }
 
 WSLUA_METAMETHOD UInt64__le(lua_State* L) {
-    /* Returns true if first `UInt64` <= second.
+    /* Returns true if first <<lua_class_UInt64,`UInt64`>> is less than or equal to the second.
        @since 1.11.3
      */
     WSLUA_COMP_OP_FUNC(UInt64,<=);
 }
 
 WSLUA_METHOD UInt64_bnot(lua_State* L) {
-    /* Returns a `UInt64` of the bitwise 'not' operation.
+    /* Returns a <<lua_class_UInt64,`UInt64`>> of the bitwise 'not' operation.
        @since 1.11.3
      */
     pushUInt64(L,~(getUInt64(L,1)));
-    WSLUA_RETURN(1); /* The `UInt64` object. */
+    WSLUA_RETURN(1); /* The <<lua_class_UInt64,`UInt64`>> object. */
 }
 
 WSLUA_METHOD UInt64_band(lua_State* L) {
-    /* Returns a `UInt64` of the bitwise 'and' operation, with the given number/`Int64`/`UInt64`.
+    /* Returns a <<lua_class_UInt64,`UInt64`>> of the bitwise 'and' operation, with the given number/`Int64`/`UInt64`.
        Note that multiple arguments are allowed.
        @since 1.11.3
      */
@@ -963,7 +1013,7 @@ WSLUA_METHOD UInt64_band(lua_State* L) {
 }
 
 WSLUA_METHOD UInt64_bor(lua_State* L) {
-    /* Returns a `UInt64` of the bitwise 'or' operation, with the given number/`Int64`/`UInt64`.
+    /* Returns a <<lua_class_UInt64,`UInt64`>> of the bitwise 'or' operation, with the given number/`Int64`/`UInt64`.
        Note that multiple arguments are allowed.
        @since 1.11.3
      */
@@ -971,7 +1021,7 @@ WSLUA_METHOD UInt64_bor(lua_State* L) {
 }
 
 WSLUA_METHOD UInt64_bxor(lua_State* L) {
-    /* Returns a `UInt64` of the bitwise 'xor' operation, with the given number/`Int64`/`UInt64`.
+    /* Returns a <<lua_class_UInt64,`UInt64`>> of the bitwise 'xor' operation, with the given number/`Int64`/`UInt64`.
        Note that multiple arguments are allowed.
        @since 1.11.3
      */
@@ -979,7 +1029,7 @@ WSLUA_METHOD UInt64_bxor(lua_State* L) {
 }
 
 WSLUA_METHOD UInt64_lshift(lua_State* L) {
-    /* Returns a `UInt64` of the bitwise logical left-shift operation, by the
+    /* Returns a <<lua_class_UInt64,`UInt64`>> of the bitwise logical left-shift operation, by the
        given number of bits.
        @since 1.11.3
      */
@@ -987,11 +1037,11 @@ WSLUA_METHOD UInt64_lshift(lua_State* L) {
     guint64 b = getUInt64(L,1);
     guint32 n = wslua_checkguint32(L,WSLUA_ARG_UInt64_lshift_NUMBITS);
     pushUInt64(L,(b << n));
-    WSLUA_RETURN(1); /* The `UInt64` object. */
+    WSLUA_RETURN(1); /* The <<lua_class_UInt64,`UInt64`>> object. */
 }
 
 WSLUA_METHOD UInt64_rshift(lua_State* L) {
-    /* Returns a `UInt64` of the bitwise logical right-shift operation, by the
+    /* Returns a <<lua_class_UInt64,`UInt64`>> of the bitwise logical right-shift operation, by the
        given number of bits.
        @since 1.11.3
      */
@@ -999,11 +1049,11 @@ WSLUA_METHOD UInt64_rshift(lua_State* L) {
     guint64 b = getUInt64(L,1);
     guint32 n = wslua_checkguint32(L,WSLUA_ARG_UInt64_rshift_NUMBITS);
     pushUInt64(L,(b >> n));
-    WSLUA_RETURN(1); /* The `UInt64` object. */
+    WSLUA_RETURN(1); /* The <<lua_class_UInt64,`UInt64`>> object. */
 }
 
 WSLUA_METHOD UInt64_arshift(lua_State* L) {
-    /* Returns a `UInt64` of the bitwise arithmetic right-shift operation, by the
+    /* Returns a <<lua_class_UInt64,`UInt64`>> of the bitwise arithmetic right-shift operation, by the
        given number of bits.
        @since 1.11.3
      */
@@ -1011,11 +1061,11 @@ WSLUA_METHOD UInt64_arshift(lua_State* L) {
     guint64 b = getUInt64(L,1);
     guint32 n = wslua_checkguint32(L,WSLUA_ARG_UInt64_arshift_NUMBITS);
     pushUInt64(L,(b >> n));
-    WSLUA_RETURN(1); /* The `UInt64` object. */
+    WSLUA_RETURN(1); /* The <<lua_class_UInt64,`UInt64`>> object. */
 }
 
 WSLUA_METHOD UInt64_rol(lua_State* L) {
-    /* Returns a `UInt64` of the bitwise left rotation operation, by the
+    /* Returns a <<lua_class_UInt64,`UInt64`>> of the bitwise left rotation operation, by the
        given number of bits (up to 63).
        @since 1.11.3
      */
@@ -1023,11 +1073,11 @@ WSLUA_METHOD UInt64_rol(lua_State* L) {
     guint64 b = getUInt64(L,1);
     guint32 n = wslua_checkguint32(L,WSLUA_ARG_UInt64_rol_NUMBITS);
     pushUInt64(L,((b << n) | (b >> (64-n))));
-    WSLUA_RETURN(1); /* The `UInt64` object. */
+    WSLUA_RETURN(1); /* The <<lua_class_UInt64,`UInt64`>> object. */
 }
 
 WSLUA_METHOD UInt64_ror(lua_State* L) {
-    /* Returns a `UInt64` of the bitwise right rotation operation, by the
+    /* Returns a <<lua_class_UInt64,`UInt64`>> of the bitwise right rotation operation, by the
        given number of bits (up to 63).
        @since 1.11.3
      */
@@ -1035,11 +1085,11 @@ WSLUA_METHOD UInt64_ror(lua_State* L) {
     guint64 b = getUInt64(L,1);
     guint32 n = wslua_checkguint32(L,WSLUA_ARG_UInt64_ror_NUMBITS);
     pushUInt64(L,((b << (64-n)) | (b >> n)));
-    WSLUA_RETURN(1); /* The `UInt64` object. */
+    WSLUA_RETURN(1); /* The <<lua_class_UInt64,`UInt64`>> object. */
 }
 
 WSLUA_METHOD UInt64_bswap(lua_State* L) {
-    /* Returns a `UInt64` of the bytes swapped. This can be used to convert little-endian
+    /* Returns a <<lua_class_UInt64,`UInt64`>> of the bytes swapped. This can be used to convert little-endian
        64-bit numbers to big-endian 64 bit numbers or vice versa.
        @since 1.11.3
      */
@@ -1052,7 +1102,7 @@ WSLUA_METHOD UInt64_bswap(lua_State* L) {
         b >>= 8;
     }
     pushUInt64(L,result);
-    WSLUA_RETURN(1); /* The `UInt64` object. */
+    WSLUA_RETURN(1); /* The <<lua_class_UInt64,`UInt64`>> object. */
 }
 
 /* Gets registered as metamethod automatically by WSLUA_REGISTER_CLASS/META */