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, 27 insertions, 132 deletions

diff --git a/epan/wslua/wslua_util.c b/epan/wslua/wslua_util.c
index f66310bf7c..c9098aa980 100644
--- a/epan/wslua/wslua_util.c
+++ b/epan/wslua/wslua_util.c
@@ -31,13 +31,13 @@
 #include <epan/stat_cmd_args.h>
 
 
-WSLUA_FUNCTION wslua_get_version(lua_State* L) { /* Get Wireshark version */
+WSLUA_FUNCTION wslua_get_version(lua_State* L) { /* Gets a string of the Wireshark version. */
     const gchar* str = VERSION;
     lua_pushstring(L,str);
     WSLUA_RETURN(1); /* version string */
 }
 
-WSLUA_FUNCTION wslua_format_date(lua_State* LS) { /* Formats an absolute timestamp into a human readable date */
+WSLUA_FUNCTION wslua_format_date(lua_State* LS) { /* Formats an absolute timestamp into a human readable date. */
 #define WSLUA_ARG_format_date_TIMESTAMP 1 /* A timestamp value to convert. */
     lua_Number timestamp = luaL_checknumber(LS,WSLUA_ARG_format_date_TIMESTAMP);
     nstime_t then;
@@ -51,8 +51,8 @@ WSLUA_FUNCTION wslua_format_date(lua_State* LS) { /* Formats an absolute timesta
     WSLUA_RETURN(1); /* A string with the formated date */
 }
 
-WSLUA_FUNCTION wslua_format_time(lua_State* LS) { /* Formats a relative timestamp in a human readable form */
-#define WSLUA_ARG_format_time_TIMESTAMP 1 /* A timestamp value to convert */
+WSLUA_FUNCTION wslua_format_time(lua_State* LS) { /* Formats a relative timestamp in a human readable form. */
+#define WSLUA_ARG_format_time_TIMESTAMP 1 /* A timestamp value to convert. */
     lua_Number timestamp = luaL_checknumber(LS,WSLUA_ARG_format_time_TIMESTAMP);
     nstime_t then;
     gchar* str;
@@ -65,8 +65,8 @@ WSLUA_FUNCTION wslua_format_time(lua_State* LS) { /* Formats a relative timestam
     WSLUA_RETURN(1); /* A string with the formated time */
 }
 
-WSLUA_FUNCTION wslua_report_failure(lua_State* LS) { /* Reports a failure to the user */
-#define WSLUA_ARG_report_failure_TEXT 1 /* Message */
+WSLUA_FUNCTION wslua_report_failure(lua_State* LS) { /* Reports a failure to the user. */
+#define WSLUA_ARG_report_failure_TEXT 1 /* Message text to report. */
     const gchar* s = luaL_checkstring(LS,WSLUA_ARG_report_failure_TEXT);
     report_failure("%s",s);
     return 0;
@@ -99,27 +99,27 @@ static int wslua_log(lua_State* L, GLogLevelFlags log_level) {
     return 0;
 }
 
-WSLUA_FUNCTION wslua_critical( lua_State* L ) { /* Will add a log entry with critical severity*/
+WSLUA_FUNCTION wslua_critical( lua_State* L ) { /* Will add a log entry with critical severity. */
 /* WSLUA_MOREARGS critical objects to be printed    */
     wslua_log(L,G_LOG_LEVEL_CRITICAL);
     return 0;
 }
-WSLUA_FUNCTION wslua_warn( lua_State* L ) { /* Will add a log entry with warn severity */
+WSLUA_FUNCTION wslua_warn( lua_State* L ) { /* Will add a log entry with warn severity. */
 /* WSLUA_MOREARGS warn objects to be printed    */
     wslua_log(L,G_LOG_LEVEL_WARNING);
     return 0;
 }
-WSLUA_FUNCTION wslua_message( lua_State* L ) { /* Will add a log entry with message severity */
+WSLUA_FUNCTION wslua_message( lua_State* L ) { /* Will add a log entry with message severity. */
 /* WSLUA_MOREARGS message objects to be printed    */
     wslua_log(L,G_LOG_LEVEL_MESSAGE);
     return 0;
 }
-WSLUA_FUNCTION wslua_info( lua_State* L ) { /* Will add a log entry with info severity */
+WSLUA_FUNCTION wslua_info( lua_State* L ) { /* Will add a log entry with info severity. */
 /* WSLUA_MOREARGS info objects to be printed    */
     wslua_log(L,G_LOG_LEVEL_INFO);
     return 0;
 }
-WSLUA_FUNCTION wslua_debug( lua_State* L ) { /* Will add a log entry with debug severity */
+WSLUA_FUNCTION wslua_debug( lua_State* L ) { /* Will add a log entry with debug severity. */
 /* WSLUA_MOREARGS debug objects to be printed    */
     wslua_log(L,G_LOG_LEVEL_DEBUG);
     return 0;
@@ -177,8 +177,8 @@ static char* wslua_get_actual_filename(const char* fname) {
 
 WSLUA_FUNCTION wslua_loadfile(lua_State* L) {
     /* Lua's loadfile() has been modified so that if a file does not exist
-    in the current directory it will look for it in wireshark's user and system directories */
-#define WSLUA_ARG_loadfile_FILENAME 1 /* Name of the file to be loaded */
+    in the current directory it will look for it in wireshark's user and system directories. */
+#define WSLUA_ARG_loadfile_FILENAME 1 /* Name of the file to be loaded. */
     const char *given_fname = luaL_checkstring(L, WSLUA_ARG_loadfile_FILENAME);
     char* filename;
 
@@ -202,8 +202,8 @@ WSLUA_FUNCTION wslua_loadfile(lua_State* L) {
 
 WSLUA_FUNCTION wslua_dofile(lua_State* L) {
     /* Lua's dofile() has been modified so that if a file does not exist
-    in the current directory it will look for it in wireshark's user and system directories */
-#define WSLUA_ARG_dofile_FILENAME 1 /* Name of the file to be run */
+    in the current directory it will look for it in wireshark's user and system directories. */
+#define WSLUA_ARG_dofile_FILENAME 1 /* Name of the file to be run. */
     const char *given_fname = luaL_checkstring(L, WSLUA_ARG_dofile_FILENAME);
     char* filename;
     int n;
@@ -229,13 +229,13 @@ WSLUA_FUNCTION wslua_dofile(lua_State* L) {
 
 
 WSLUA_FUNCTION wslua_persconffile_path(lua_State* L) {
-#define WSLUA_OPTARG_persconffile_path_FILENAME 1 /* A filename */
+#define WSLUA_OPTARG_persconffile_path_FILENAME 1 /* A filename. */
     const char *fname = luaL_optstring(L, WSLUA_OPTARG_persconffile_path_FILENAME,"");
     char* filename = get_persconffile_path(fname,FALSE);
 
     lua_pushstring(L,filename);
     g_free(filename);
-    WSLUA_RETURN(1); /* The full pathname for a file in the personal configuration directory */
+    WSLUA_RETURN(1); /* The full pathname for a file in the personal configuration directory. */
 }
 
 WSLUA_FUNCTION wslua_datafile_path(lua_State* L) {
@@ -253,16 +253,19 @@ WSLUA_FUNCTION wslua_datafile_path(lua_State* L) {
 
     lua_pushstring(L,filename);
     g_free(filename);
-    WSLUA_RETURN(1); /* The full pathname for a file in wireshark's configuration directory */
+    WSLUA_RETURN(1); /* The full pathname for a file in wireshark's configuration directory. */
 }
 
 
 WSLUA_CLASS_DEFINE(Dir,FAIL_ON_NULL("Dir"),NOP); /* A Directory */
 
 WSLUA_CONSTRUCTOR Dir_open(lua_State* L) {
-    /* Usage: for filename in Dir.open(path) do ... end */
-#define WSLUA_ARG_Dir_open_PATHNAME 1 /* The pathname of the directory */
-#define WSLUA_OPTARG_Dir_open_EXTENSION 2 /* If given, only file with this extension will be returned */
+    /* Opens a directory and returns a `Dir` object representing the files in the directory.
+
+       @code for filename in Dir.open(path) do ... end @endcode
+    */
+#define WSLUA_ARG_Dir_open_PATHNAME 1 /* The pathname of the directory. */
+#define WSLUA_OPTARG_Dir_open_EXTENSION 2 /* If given, only files with this extension will be returned. */
 
     const char* dirname = luaL_checkstring(L,WSLUA_ARG_Dir_open_PATHNAME);
     const char* extension = luaL_optstring(L,WSLUA_OPTARG_Dir_open_EXTENSION,NULL);
@@ -302,11 +305,11 @@ WSLUA_CONSTRUCTOR Dir_open(lua_State* L) {
     }
 
     pushDir(L,dir);
-    WSLUA_RETURN(1); /* the Dir object */
+    WSLUA_RETURN(1); /* the `Dir` object. */
 }
 
 WSLUA_METAMETHOD Dir__call(lua_State* L) {
-    /* At every invocation will return one file (nil when done) */
+    /* At every invocation will return one file (nil when done). */
 
     Dir dir = checkDir(L,1);
     const gchar* file;
@@ -346,7 +349,7 @@ WSLUA_METAMETHOD Dir__call(lua_State* L) {
 }
 
 WSLUA_METHOD Dir_close(lua_State* L) {
-    /* Closes the directory */
+    /* Closes the directory. */
     Dir dir = checkDir(L,1);
 
     if (dir->dir) {
@@ -446,114 +449,6 @@ WSLUA_FUNCTION wslua_register_stat_cmd_arg(lua_State* L) {
     return 0;
 }
 
-/* Pushes a hex string of the binary data argument. */
-int wslua_bin2hex(lua_State* L, const guint8* data, const guint len, const gboolean lowercase, const gchar* sep) {
-    luaL_Buffer b;
-    guint i = 0;
-    static const char byte_to_str_upper[256][3] = {
-        "00","01","02","03","04","05","06","07","08","09","0A","0B","0C","0D","0E","0F",
-        "10","11","12","13","14","15","16","17","18","19","1A","1B","1C","1D","1E","1F",
-        "20","21","22","23","24","25","26","27","28","29","2A","2B","2C","2D","2E","2F",
-        "30","31","32","33","34","35","36","37","38","39","3A","3B","3C","3D","3E","3F",
-        "40","41","42","43","44","45","46","47","48","49","4A","4B","4C","4D","4E","4F",
-        "50","51","52","53","54","55","56","57","58","59","5A","5B","5C","5D","5E","5F",
-        "60","61","62","63","64","65","66","67","68","69","6A","6B","6C","6D","6E","6F",
-        "70","71","72","73","74","75","76","77","78","79","7A","7B","7C","7D","7E","7F",
-        "80","81","82","83","84","85","86","87","88","89","8A","8B","8C","8D","8E","8F",
-        "90","91","92","93","94","95","96","97","98","99","9A","9B","9C","9D","9E","9F",
-        "A0","A1","A2","A3","A4","A5","A6","A7","A8","A9","AA","AB","AC","AD","AE","AF",
-        "B0","B1","B2","B3","B4","B5","B6","B7","B8","B9","BA","BB","BC","BD","BE","BF",
-        "C0","C1","C2","C3","C4","C5","C6","C7","C8","C9","CA","CB","CC","CD","CE","CF",
-        "D0","D1","D2","D3","D4","D5","D6","D7","D8","D9","DA","DB","DC","DD","DE","DF",
-        "E0","E1","E2","E3","E4","E5","E6","E7","E8","E9","EA","EB","EC","ED","EE","EF",
-        "F0","F1","F2","F3","F4","F5","F6","F7","F8","F9","FA","FB","FC","FD","FE","FF"
-    };
-    static const char byte_to_str_lower[256][3] = {
-        "00","01","02","03","04","05","06","07","08","09","0a","0b","0c","0d","0e","0f",
-        "10","11","12","13","14","15","16","17","18","19","1a","1b","1c","1d","1e","1f",
-        "20","21","22","23","24","25","26","27","28","29","2a","2b","2c","2d","2e","2f",
-        "30","31","32","33","34","35","36","37","38","39","3a","3b","3c","3d","3e","3f",
-        "40","41","42","43","44","45","46","47","48","49","4a","4b","4c","4d","4e","4f",
-        "50","51","52","53","54","55","56","57","58","59","5a","5b","5c","5d","5e","5f",
-        "60","61","62","63","64","65","66","67","68","69","6a","6b","6c","6d","6e","6f",
-        "70","71","72","73","74","75","76","77","78","79","7a","7b","7c","7d","7e","7f",
-        "80","81","82","83","84","85","86","87","88","89","8a","8b","8c","8d","8e","8f",
-        "90","91","92","93","94","95","96","97","98","99","9a","9b","9c","9d","9e","9f",
-        "a0","a1","a2","a3","a4","a5","a6","a7","a8","a9","aa","ab","ac","ad","ae","af",
-        "b0","b1","b2","b3","b4","b5","b6","b7","b8","b9","ba","bb","bc","bd","be","bf",
-        "c0","c1","c2","c3","c4","c5","c6","c7","c8","c9","ca","cb","cc","cd","ce","cf",
-        "d0","d1","d2","d3","d4","d5","d6","d7","d8","d9","da","db","dc","dd","de","df",
-        "e0","e1","e2","e3","e4","e5","e6","e7","e8","e9","ea","eb","ec","ed","ee","ef",
-        "f0","f1","f2","f3","f4","f5","f6","f7","f8","f9","fa","fb","fc","fd","fe","ff"
-    };
-    const char (*byte_to_str)[3] = byte_to_str_upper;
-    const guint last = len - 1;
-
-    if (lowercase) byte_to_str = byte_to_str_lower;
-
-    luaL_buffinit(L, &b);
-
-    for (i = 0; i < len; i++) {
-        luaL_addlstring(&b, &(*byte_to_str[data[i]]), 2);
-        if (sep && i < last) luaL_addstring(&b, sep);
-    }
-
-    luaL_pushresult(&b);
-
-    return 1;
-}
-
-/* Pushes a binary string of the hex-ascii data argument. */
-int wslua_hex2bin(lua_State* L, const char* data, const guint len, const gchar* sep) {
-    luaL_Buffer b;
-    guint i = 0;
-    guint seplen = 0;
-    char c, d;
-
-    static const char str_to_nibble[256] = {
-        -1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,
-        -1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,
-        -1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,
-         0, 1, 2, 3, 4, 5, 6, 7, 8, 9,-1,-1,-1,-1,-1,-1,
-        -1,10,11,12,13,14,15,-1,-1,-1,-1,-1,-1,-1,-1,-1,
-        -1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,
-        -1,10,11,12,13,14,15,-1,-1,-1,-1,-1,-1,-1,-1,-1,
-        -1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,
-        -1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,
-        -1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,
-        -1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,
-        -1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,
-        -1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,
-        -1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,
-        -1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,
-        -1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1
-    };
-
-    if (sep) seplen = (guint) strlen(sep);
-
-    luaL_buffinit(L, &b);
-
-    for (i = 0; i < len;) {
-        c = str_to_nibble[(int)data[i]];
-        if (c < 0) {
-            if (seplen && strncmp(&data[i], sep, seplen) == 0) {
-                i += seplen;
-                continue;
-            } else {
-                break;
-            }
-        }
-        d = str_to_nibble[(int)data[++i]];
-        if (d < 0) break;
-        luaL_addchar(&b, (c * 16) + d);
-        i++;
-    }
-
-    luaL_pushresult(&b);
-
-    return 1;
-}
-
 /*
  * Editor modelines  -  http://www.wireshark.org/tools/modelines.html
  *