Have Lua disabled by default.

Add more documentation to the code. 
change make-dco.pl so that it creates more readable docbook output.

This should be copied over to 0.99.4



svn path=/trunk/; revision=19670

9 files changed, 193 insertions, 132 deletions

diff --git a/epan/wslua/Makefile.am b/epan/wslua/Makefile.am
index 3a472567d3..c2c4fec0d8 100644
--- a/epan/wslua/Makefile.am
+++ b/epan/wslua/Makefile.am
@@ -67,7 +67,6 @@ MAINTAINERCLEANFILES = \
 	Makefile.in	\
 	register_wslua.c \
 	declare_wslua.h \
-	doc/*.pod	\
 	init.lua
 
 EXTRA_DIST = \
@@ -102,7 +101,7 @@ register_wslua.c: declare_wslua.h
 declare_wslua.h: make-reg.pl $(wslua_modules) taps_wslua.c
 	$(PERL) $(srcdir)/make-reg.pl $(wslua_modules);
 
-doc: make-doc.pl $(wslua_modules) template-wsluarm.xml
+doc: dummy
 	$(PERL) $(srcdir)/make-doc.pl $(wslua_modules)
 
 dummy:
diff --git a/epan/wslua/make-doc.pl b/epan/wslua/make-doc.pl
index 0a198c255c..4ab4dbee64 100755
--- a/epan/wslua/make-doc.pl
+++ b/epan/wslua/make-doc.pl
@@ -35,7 +35,7 @@ sub deb {
 }
 
 sub gorolla {
-# a gorilla stays to a chimp like ... stays to chomp 
+# a gorilla stays to a chimp like gorolla stays to chomp 
 # but this one returns the shrugged string.
 	my $s = shift;
 	$s =~ s/^([\n]|\s)*//ms;
@@ -53,8 +53,8 @@ my $function;
 my @functions;
 
 my $docbook_template = {
-	module_header => "<chapter id='lua_module_%s'>\n\t<title>%s</title>\n",
-	module_desc => "\t<para>%s</para>\n",
+	module_header => "<chapter id='lua_module_%s'>\n",
+	module_desc => "\t<title>%s</title>\n",
 	module_footer => "</chapter>\n",
 	class_header => "\t<section id='lua_class_%s'><title>%s</title>\n",
 	class_footer => "\t</section> <!-- class_footer: %s -->\n",
@@ -71,18 +71,20 @@ my $docbook_template = {
 	function_header => "\t\t\t<section id='lua_fn_%s'>\n\t\t\t\t<title>%s</title>\n",
 	function_descr => "\t\t\t\t<para>%s</para>\n",
 	function_footer => "\t\t\t</section> <!-- function_footer: %s -->\n",
-	function_arg_header => "\t\t\t\t<section id='lua_fn_arg_%s'>\n\t\t\t\t\t<title>%s</title>\n",
-	function_arg_descr => "\t\t\t\t\t<para>%s</para>\n",
-	function_arg_footer => "\t\t\t\t</section> <!-- function_arg_footer: %s -->\n",
-	function_argerror_header => "\t\t\t\t\t<section id='lua_fn_argerr_%s'>\n\t\t\t\t\t\t<title>Errors</title>\n\t\t\t\t\t\t<itemizedlist>\n",
+	function_args_header => "\t\t\t\t\t<command>Arguments</command>\t\t\t\t<variablelist>\n",
+	function_args_footer => "\t\t\t\t</variablelist>\n",
+	function_arg_header => "\t\t\t\t<varlistentry><term>%s</term>\n",
+	function_arg_descr => "\t\t\t\t\t<listitem><para>%s</para></listitem>\n",
+	function_arg_footer => "\t\t\t\t</varlistentry> <!-- function_arg_footer: %s -->\n",
+	function_argerror_header => "\t\t\t\t\t<command>Errors</command>\n\t\t\t\t\t\t<itemizedlist>\n",
 	function_argerror => "\t\t\t\t\t\t\t<listitem><para>%s</para></listitem>\n",
-	function_argerror_footer => "\t\t\t\t\t\t</itemizedlist>\n\t\t\t\t\t</section> <!-- function_argerror_footer: %s -->\n",
-	function_returns_header => "\t\t\t\t<section id='lua_fn_ret_%s'><title>Returns</title>\n",
-	function_returns_footer => "\t\t\t\t</section> <!-- function_returns_footer: %s -->\n",
+	function_argerror_footer => "\t\t\t\t\t\t</itemizedlist> <!-- function_argerror_footer: %s -->\n",
+	function_returns_header => "\t\t\t\t<command>Returns</command>\n",
+#	function_returns_footer => "\t\t\t\t</section> <!-- function_returns_footer: %s -->\n",
 	function_returns => "\t\t\t\t\t<para>%s</para>\n",
-	function_errors_header => "\t\t\t\t<section id='lua_fn_err_%s'>\n\t\t\t\t\t<title>Errors</title>\n\t\t\t\t\t<itemizedlist>\n",
+	function_errors_header => "\t\t\t\t<command>Errors</command><itemizedlist>\n",
 	function_errors => "\t\t\t\t\t\t<listitem><para>%s</para></listitem>\n",
-	function_errors_footer => "\t\t\t\t\t</itemizedlist>\n\t\t\t\t</section> <!-- function_error_footer: %s -->\n",
+	function_errors_footer => "\t\t\t\t\t</itemizedlist> <!-- function_error_footer: %s -->\n",
 	non_method_functions_header => "\t\t<section id='non_method_functions_%s'><title>Non Method Functions</title>\n",
 	non_method_functions_footer => "\t\t</section> <!-- Non method -->\n",
 };
@@ -209,15 +211,12 @@ sub {
 		deb ">cm=$1=$2=$3=$4=$5=$6=$7=\n";
 		my $name = $metamethods{$2};
 		my ($c,$d) = ($1,$5);
-		my $sname = $2;
-		$name =~ s/__/$c/g;
 		$function = {
 			returns => [],
 			arglist => [],
 			args => {},
-			name => $name,
-			section_name => $sname,
-			descr => gorolla($d),
+			name => "$1:$2",
+			descr => gorolla($5),
 			type => 'metamethod'
 		};
 		push @{${$class}{metamethods}}, $function;
@@ -332,33 +331,27 @@ while ( $file =  shift) {
 		printf D ${$template_ref}{class_desc} , ${$cl}{descr} if ${$cl}{descr};
 		
 		if ( $#{${$cl}{constructors}} >= 0) {
-			printf D ${$template_ref}{class_constructors_header}, $cname, $cname;
+#			printf D ${$template_ref}{class_constructors_header}, $cname, $cname;
 			
 			for my $c (@{${$cl}{constructors}}) {
 				function_descr($c);
 			}
 
-			printf D ${$template_ref}{class_constructors_footer}, $cname, $cname;
+#			printf D ${$template_ref}{class_constructors_footer}, $cname, $cname;
 		}
 
 		if ( $#{${$cl}{methods}} >= 0) {
-			printf D ${$template_ref}{class_methods_header}, $cname, $cname;
+#			printf D ${$template_ref}{class_methods_header}, $cname, $cname;
 			
 			for my $m (@{${$cl}{methods}}) {
 				function_descr($m);
 			}
 			
-			printf D ${$template_ref}{class_methods_footer}, $cname, $cname;
-		}
-		
-		if ( $#{${$cl}{metamethods}} >= 0) {
-			printf D ${$template_ref}{class_metamethods_header}, $cname, $cname;
-			
 			for my $m (@{${$cl}{metamethods}}) {
-				function_descr($m,${$m}{name});
+				function_descr($m);
 			}
 			
-			printf D ${$template_ref}{class_metamethods_footer}, $cname, $cname;
+#			printf D ${$template_ref}{class_methods_footer}, $cname, $cname;
 		}
 		
 		if ( $#{${$cl}{attributes}} >= 0) {
@@ -409,7 +402,7 @@ close B;
 my $ents = '';
 my $txt = '';
 
-for my $module_name (keys %modules) {
+for my $module_name (sort keys %modules) {
 	$ents .= <<"_ENT";
 	<!ENTITY $module_name SYSTEM "$modules{$module_name}">
 _ENT
@@ -446,6 +439,8 @@ sub function_descr {
 	}	
 	
 	printf D ${$template_ref}{function_descr}, ${$f}{descr} if ${$f}{descr};
+
+	print D ${$template_ref}{function_args_header} if $#{${$f}{arglist}} >= 0;
 	
 	for my $argname (@{${$f}{arglist}}) {
 		my $arg = ${${$f}{args}}{$argname};
@@ -464,6 +459,8 @@ sub function_descr {
 	
 	}
 	
+	print D ${$template_ref}{function_args_footer} if $#{${$f}{arglist}} >= 0;
+	
 	if ( $#{${$f}{returns}} >= 0) {
 		printf D ${$template_ref}{function_returns_header}, ${$f}{name};
 		printf D ${$template_ref}{function_returns}, $_ for @{${$f}{returns}};
diff --git a/epan/wslua/template-init.lua b/epan/wslua/template-init.lua
index 6eae877f97..24dc4156e2 100644
--- a/epan/wslua/template-init.lua
+++ b/epan/wslua/template-init.lua
@@ -25,8 +25,8 @@
 -- along with this program; if not, write to the Free Software
 -- Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
 
--- If lua is to be completely disabled uncomment the following line.
--- disable_lua = true; do return end;
+-- Lua is disabled by default, comment out the following line to enable Lua support.
+disable_lua = true; do return end;
 
 
 -- If set and we are running with special privileges this setting
@@ -48,7 +48,7 @@ if running_superuser then
     file = disabled_lib
 end
 
--- to avoid output to stdout which can caause problems lua's print ()
+-- to avoid output to stdout which can cause problems lua's print ()
 -- has been suppresed so that it yields an error.
 -- have print() call info() instead.
 print = info
diff --git a/epan/wslua/wslua_gui.c b/epan/wslua/wslua_gui.c
index 306cf83e5d..8b799ce5aa 100644
--- a/epan/wslua/wslua_gui.c
+++ b/epan/wslua/wslua_gui.c
@@ -26,7 +26,7 @@
 
 #include "wslua.h"
 
-/* WSLUA_MODULE Gui Gui Support*/ 
+/* WSLUA_MODULE Gui GUI support */
 
 static const funnel_ops_t* ops = NULL;
 
diff --git a/epan/wslua/wslua_pinfo.c b/epan/wslua/wslua_pinfo.c
index 28608fc7c9..0ea51ed085 100644
--- a/epan/wslua/wslua_pinfo.c
+++ b/epan/wslua/wslua_pinfo.c
@@ -62,7 +62,9 @@ void* push_Pinfo(lua_State* L, Pinfo pinfo) {
 
 WSLUA_CLASS_DEFINE(Address,NOP,NOP); /* Represents an address */
 
-WSLUA_CONSTRUCTOR Address_ip(lua_State* L) { /* Creates an Address Object representing an IP address. */
+WSLUA_CONSTRUCTOR Address_ip(lua_State* L) {
+	/* Creates an Address Object representing an IP address. */
+	
 #define WSLUA_ARG_Address_ip_HOSTNAME 1 /* The address or name of the IP host. */
     Address addr = g_malloc(sizeof(address));
     guint32* ip_addr = g_malloc(sizeof(guint32));
diff --git a/epan/wslua/wslua_proto.c b/epan/wslua/wslua_proto.c
index 3d32ebdcb4..c0618a1f84 100644
--- a/epan/wslua/wslua_proto.c
+++ b/epan/wslua/wslua_proto.c
@@ -137,7 +137,7 @@ WSLUA_CLASS_DEFINE(Prefs,NOP,NOP); /* The table of preferences of a protocol */
 WSLUA_METAMETHOD Prefs__newindex(lua_State* L) {
 	/* creates a new preference */
 #define WSLUA_ARG_Prefs__newindex_NAME 2 /* The abbreviation of this preference */
-#define WSLUA_ARG_Prefs__newindex_PREF 3 /* A valid still unassigned Pref object */
+#define WSLUA_ARG_Prefs__newindex_PREF 3 /* A valid but still unassigned Pref object */
 
     Pref prefs = checkPrefs(L,1);
     const gchar* name = luaL_checkstring(L,WSLUA_ARG_Prefs__newindex_NAME);
diff --git a/epan/wslua/wslua_tree.c b/epan/wslua/wslua_tree.c
index 47ed7e448c..bc0c7d3524 100644
--- a/epan/wslua/wslua_tree.c
+++ b/epan/wslua/wslua_tree.c
@@ -51,8 +51,9 @@ void clear_outstanding_trees(void) {
 }
 
 WSLUA_CLASS_DEFINE(TreeItem,NOP,NOP);
+/* TreeItems represent information in the packet-details pane.
+   A root TreeItem is passed to dissectors as first argument. */
 
-/* ProtoTree class */
 static int TreeItem_add_item_any(lua_State *L, gboolean little_endian) {
     TvbRange tvbr;
     Proto proto;
@@ -183,10 +184,28 @@ static int TreeItem_add_item_any(lua_State *L, gboolean little_endian) {
 }
 
 
-WSLUA_METHOD TreeItem_add(lua_State *L) { return TreeItem_add_item_any(L,FALSE); }
-WSLUA_METHOD TreeItem_add_le(lua_State *L) { return TreeItem_add_item_any(L,TRUE); }
+WSLUA_METHOD TreeItem_add(lua_State *L) {
+	/*
+	 Adds an child item to a given item, returning the child.
+	 tree_item:add([proto_field | proto], [tvbrange], [label], ...)
+	 if the proto_field represents a numeric value (int, uint or float) is to be treated as a Big Endian (network order) Value.
+	*/
+	
+	WSLUA_RETURN(TreeItem_add_item_any(L,FALSE)); /* The child item */
+}
+
+WSLUA_METHOD TreeItem_add_le(lua_State *L) {
+	/*
+	 Adds (and returns) an child item to a given item, returning the child.
+	 tree_item:add([proto_field | proto], [tvbrange], [label], ...)
+	 if the proto_field represents a numeric value (int, uint or float) is to be treated as a Little Endian Value.
+	 */
+	WSLUA_RETURN(TreeItem_add_item_any(L,TRUE)); /* The child item */
+}
 
 WSLUA_METHOD TreeItem_set_text(lua_State *L) {
+	/* sets the text of the label */
+#define WSLUA_ARG_TreeItem_set_text_TEXT 2 /* The text to be used. */
     TreeItem ti = checkTreeItem(L,1);
     
     if (ti) {
@@ -198,6 +217,8 @@ WSLUA_METHOD TreeItem_set_text(lua_State *L) {
 }
 
 WSLUA_METHOD TreeItem_append_text(lua_State *L) {
+	/* appends text to the label */
+#define WSLUA_ARG_TreeItem_append_text_TEXT 2 /* The text to be appended. */
     TreeItem ti = checkTreeItem(L,1);
     const gchar* s;
     
@@ -208,22 +229,13 @@ WSLUA_METHOD TreeItem_append_text(lua_State *L) {
     return 0;
 }
 
-WSLUA_METHOD TreeItem_set_len(lua_State *L) {
-    TreeItem ti = checkTreeItem(L,1);
-    int len;
-
-    if (ti) {
-        len = luaL_checkint(L,2);
-        proto_item_set_len(ti->item,len);
-    }
-    
-    return 0;
-}
-
 WSLUA_METHOD TreeItem_set_expert_flags(lua_State *L) {
+/* Sets the expert flags of the item. */
+#define WSLUA_OPTARG_TreeItem_set_expert_flags_GROUP 2 /* One of PI_CHECKSUM, PI_SEQUENCE, PI_RESPONSE_CODE, PI_REQUEST_CODE, PI_UNDECODED, PI_REASSEMBLE, PI_MALFORMED or PI_DEBUG */
+#define WSLUA_OPTARG_TreeItem_set_expert_flags_SEVERITY 3 /* One of PI_CHAT, PI_NOTE, PI_WARN, PI_ERROR */
     TreeItem ti = checkTreeItem(L,1);
-	int group = luaL_checkint(L,2);
-	int severity = luaL_checkint(L,3);
+	int group = luaL_optint(L,2,PI_DEBUG);
+	int severity = luaL_optint(L,3,PI_CHAT);
 
     if ( ti && ti->item ) {
             proto_item_set_expert_flags(ti->item,group,severity);
@@ -233,9 +245,13 @@ WSLUA_METHOD TreeItem_set_expert_flags(lua_State *L) {
 }
 
 WSLUA_METHOD TreeItem_add_expert_info(lua_State *L) {
+	/* Sets the expert flags of the item and adds expert info to the packet. */
+#define WSLUA_OPTARG_TreeItem_add_expert_info_GROUP 2 /* One of PI_CHECKSUM, PI_SEQUENCE, PI_RESPONSE_CODE, PI_REQUEST_CODE, PI_UNDECODED, PI_REASSEMBLE, PI_MALFORMED or PI_DEBUG */
+#define WSLUA_OPTARG_TreeItem_add_expert_info_SEVERITY 3 /* One of PI_CHAT, PI_NOTE, PI_WARN, PI_ERROR */
+#define WSLUA_OPTARG_TreeItem_add_expert_info_TEXT 3 /* the text for the expert info */
     TreeItem ti = checkTreeItem(L,1);
-	int group = luaL_checkint(L,2);
-	int severity = luaL_checkint(L,3);
+	int group = luaL_optint(L,2,PI_DEBUG);
+	int severity = luaL_optint(L,3,PI_CHAT);
 	const gchar* str = luaL_optstring(L,4,"Expert Info");
 	
     if ( ti && ti->item ) {
@@ -246,6 +262,7 @@ WSLUA_METHOD TreeItem_add_expert_info(lua_State *L) {
 }
 
 WSLUA_METHOD TreeItem_set_generated(lua_State *L) {
+	/* marks the TreeItem as a generated field (with data infered but not contained in the packet). */
     TreeItem ti = checkTreeItem(L,1);
     if (ti) {
         PROTO_ITEM_SET_GENERATED(ti->item);
@@ -255,6 +272,7 @@ WSLUA_METHOD TreeItem_set_generated(lua_State *L) {
 
 
 WSLUA_METHOD TreeItem_set_hidden(lua_State *L) {
+	/* should not be used */
     TreeItem ti = checkTreeItem(L,1);
     if (ti) {
         PROTO_ITEM_SET_HIDDEN(ti->item);
@@ -267,7 +285,6 @@ static const luaL_reg TreeItem_methods[] = {
     {"add_le",       TreeItem_add_le},
     {"set_text",       TreeItem_set_text},
     {"append_text",       TreeItem_append_text},
-    {"set_len",       TreeItem_set_len},
     {"set_expert_flags",       TreeItem_set_expert_flags},
     {"add_expert_info",       TreeItem_add_expert_info},
     {"set_generated",       TreeItem_set_generated},
diff --git a/epan/wslua/wslua_tvb.c b/epan/wslua/wslua_tvb.c
index 4dbeec95a7..490ba11170 100644
--- a/epan/wslua/wslua_tvb.c
+++ b/epan/wslua/wslua_tvb.c
@@ -87,6 +87,7 @@ static int ByteArray_gc(lua_State* L) {
 }
 
 WSLUA_METAMETHOD ByteArray__concat(lua_State* L) {
+	/* concatenate two ByteArrays */
 #define WSLUA_ARG_ByteArray__cat_FIRST 1
 #define WSLUA_ARG_ByteArray__cat_SECOND 1
 	
@@ -103,7 +104,8 @@ WSLUA_METAMETHOD ByteArray__concat(lua_State* L) {
 }
 
 WSLUA_METHOD ByteArray_prepend(lua_State* L) {
-#define WSLUA_ARG_ByteArray_prepend_BYTES 1
+	/* prepend a ByteArray to this ByteArray */
+#define WSLUA_ARG_ByteArray_prepend_PREPENDED 2
     ByteArray ba = checkByteArray(L,1);
     ByteArray ba2 = checkByteArray(L,2);
     
@@ -117,6 +119,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
     ByteArray ba = checkByteArray(L,1);
     ByteArray ba2 = checkByteArray(L,2);
     
@@ -130,6 +134,9 @@ 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
+
     ByteArray ba = checkByteArray(L,1);
     int siz = luaL_checkint(L,2);
 
@@ -140,6 +147,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] */
     ByteArray ba = checkByteArray(L,1);
     int idx = luaL_checkint(L,2);
     int v = luaL_checkint(L,3);
@@ -168,6 +178,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_set_index_INDEX 2 /* the position of the byte to be set */
     ByteArray ba = checkByteArray(L,1);
     int idx = luaL_checkint(L,2);
     
@@ -184,20 +196,24 @@ WSLUA_METHOD ByteArray_get_index(lua_State* L) {
     }
     lua_pushnumber(L,ba->data[idx]);
     
-    return 1;
+    WSLUA_RETURN(1); /* The value [0-255] of the byte. */
 }
 
 WSLUA_METHOD ByteArray_len(lua_State* L) {
+	/* obtain the length of a ByteArray */
     ByteArray ba = checkByteArray(L,1);
     
     if (!ba) return 0;
     
     lua_pushnumber(L,(lua_Number)ba->len);
 
-    return 1;
+    WSLUA_RETURN(1); /* The length of the ByteArray. */
 }
 
 WSLUA_METHOD ByteArray_subset(lua_State* L) {
+	/* obtain a segment of a ByteArray */
+#define WSLUA_ARG_ByteArray_set_index_OFFSET 2 /* the position of the first byte */
+#define WSLUA_ARG_ByteArray_set_index_LENGTH 2 /* the lenght of the segment */
     ByteArray ba = checkByteArray(L,1);
     int offset = luaL_checkint(L,2);
     int len = luaL_checkint(L,3);
@@ -215,10 +231,11 @@ WSLUA_METHOD ByteArray_subset(lua_State* L) {
     
     pushByteArray(L,sub);
     
-    return 1;
+    WSLUA_RETURN(1); /* a ByteArray contaning the requested segment. */
 }
 
 static int ByteArray_tostring(lua_State* L) {
+	/* obtain a string containing the bytes in a ByteArray so that it can be used in display filters (e.g. "01:23:45:67:89:AB") */
     static const gchar* byte_to_str[] = {
         "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",
@@ -252,7 +269,7 @@ static int ByteArray_tostring(lua_State* L) {
     lua_pushstring(L,s->str);
     g_string_free(s,TRUE);
     
-    return 1;
+    WSLUA_RETURN(1); /* a string contaning a representaion of the ByteArray. */
 }
 
 static int Tvb_new_real (lua_State *L);
@@ -304,6 +321,11 @@ int ByteArray_register(lua_State* L) {
  */
 
 WSLUA_CLASS_DEFINE(Tvb,FAIL_ON_NULL("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() )*/
 
 static GPtrArray* outstanding_stuff = NULL;
 
@@ -327,9 +349,11 @@ void* push_Tvb(lua_State* L, Tvb tvb) {
 
 /*
  * Tvb_new_real(bytearray,name)
- *  Creates a new Tvb from a bytearray (adds it to the frame too)
  */
-static int Tvb_new_real (lua_State *L) {
+WSLUA_CONSTRUCTOR Tvb_new_real (lua_State *L) {
+	/* Creates a new Tvb from a bytearray (it gets added to the current frame too) */
+#define WSLUA_ARG_Tvb_new_real_BYTEARRAY 1 /* The data source for this Tvb. */
+#define WSLUA_ARG_Tvb_new_real_NAME 2 /* The name to be given to the new data-source. */
     ByteArray ba = checkByteArray(L,1);
     const gchar* name = luaL_optstring(L,2,"Unnamed") ;
     guint8* data;
@@ -349,14 +373,13 @@ static int Tvb_new_real (lua_State *L) {
     
     add_new_data_source(lua_pinfo, tvb, name);
     PUSH_TVB(L,tvb);
-    return 1;
+    WSLUA_RETURN(1); /* the created Tvb. */
 }
 
-/*
- * creates a subtvb from a tvbrange
- *
- */
-static int Tvb_new_subset (lua_State *L) {
+WSLUA_CONSTRUCTOR Tvb_new_subset (lua_State *L) {
+	/* creates a (sub)Tvb from using a TvbRange */
+#define WSLUA_ARG_Tvb_new_subset_RANGE 2 /* the TvbRange from which to create the new Tvb. */
+
     TvbRange tvbr = checkTvbRange(L,1);
     
     if (! tvbr) return 0;
@@ -370,10 +393,8 @@ static int Tvb_new_subset (lua_State *L) {
     }
 }
 
-/*
- * convert the bytes to string, mainly for debugging purposes (mind the ...)
- */
-static int Tvb_tostring(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. */
     Tvb tvb = checkTvb(L,1);
     int len;
     gchar* str;
@@ -383,32 +404,28 @@ static int Tvb_tostring(lua_State* L) {
     len = tvb_length(tvb);
     str = ep_strdup_printf("TVB(%i) : %s",len,tvb_bytes_to_str(tvb,0,len));
     lua_pushstring(L,str);
-    return 1;
+    WSLUA_RETURN(1); /* the string. */
 }
 
 
-/*
- *  returns the length of a TVB
- */
-static int Tvb_len(lua_State* L) {
+WSLUA_METHOD Tvb_len(lua_State* L) {
+	/* obtain the length of a TVB */
     Tvb tvb = checkTvb(L,1);
     
     if (!tvb) return 0;
     
     lua_pushnumber(L,tvb_length(tvb));
-    return 1;
+    WSLUA_RETURN(1); /* the lenght of the Tvb. */
 }
 
-/*
- *  returns the raw offset of a sub TVB
- */
-static int Tvb_offset(lua_State* L) {
+WSLUA_METHOD Tvb_offset(lua_State* L) {
+	/* returns the raw offset (from the beginning of the source Tvb) of a sub Tvb. */
     Tvb tvb = checkTvb(L,1);
     
     if (!tvb) return 0;
         
     lua_pushnumber(L,TVB_RAW_OFFSET(tvb));
-    return 1;
+    WSLUA_RETURN(1); /* the raw offset of the Tvb. */
 }
 
 
@@ -422,7 +439,7 @@ static int Tvb_range(lua_State* L);
 
 static const luaL_reg Tvb_meta[] = {
     {"__call", Tvb_range},
-    {"__tostring", Tvb_tostring},
+    {"__tostring", Tvb__tostring},
     {0, 0}
 };
 
@@ -431,9 +448,10 @@ int Tvb_register(lua_State* L) {
     return 1;
 }
 
+WSLUA_CLASS_DEFINE(TvbRange,FAIL_ON_NULL("expired tvbrange"),NOP);
 /*
- *  TVB RAnge helper class
- *
+ *  a TvbRange represents an 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,lenght)). If the TvbRange span is outside the Tvb's range the creation will cause a runtime error.
  */
 
 TvbRange new_TvbRange(lua_State* L, tvbuff_t* tvb, int offset, int len) {
@@ -458,10 +476,11 @@ TvbRange new_TvbRange(lua_State* L, tvbuff_t* tvb, int offset, int len) {
     return tvbr;
 }
 
-/*
- *  creates a tvbr given the triplet (tvb,offset,len)
- */
-static int Tvb_range(lua_State* L) {
+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 begining of the Tvb. Defaults to 0. */
+#define WSLUA_OPTARG_Tvb_range_LENGTH 2 /* 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,2,0);
     int len = luaL_optint(L,3,-1);
@@ -471,19 +490,21 @@ static int Tvb_range(lua_State* L) {
 
     if ((tvbr = new_TvbRange(L,tvb,offset,len))) {
         PUSH_TVBRANGE(L,tvbr);
-        return 1;
+		WSLUA_RETURN(1); /* the TvbRange */
     }
     
     return 0;
-
 }
 
-WSLUA_CLASS_DEFINE(TvbRange,FAIL_ON_NULL("expired tvbrange"),NOP);
 
 /*
  *  read access to tvbr's data
  */
 static int TvbRange_get_index(lua_State* L) {
+	/* WSLUA_ATTRIBUTE TvbRange_tvb RO The Tvb from which this TvbRange was generated */	
+	/* WSLUA_ATTRIBUTE TvbRange_len RW The lenght (in octets) of this TvbRange */	
+	/* WSLUA_ATTRIBUTE TvbRange_offset RW The offset (in octets) of this TvbRange */
+
     TvbRange tvbr = checkTvbRange(L,1);
     const gchar* index = luaL_checkstring(L,2);
     
@@ -547,7 +568,9 @@ static int TvbRange_set_index(lua_State* L) {
 /*
  *  get a Blefuscuoan unsigned integer from a tvb
  */
-static int TvbRange_get_uint(lua_State* L) {
+WSLUA_METHOD TvbRange_get_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.
+	There's no support yet for 64 bit integers*/
     TvbRange tvbr = checkTvbRange(L,1);
     if (!tvbr) return 0;
     
@@ -563,7 +586,7 @@ static int TvbRange_get_uint(lua_State* L) {
             return 1;
         case 4:
             lua_pushnumber(L,tvb_get_ntohl(tvbr->tvb,tvbr->offset));
-            return 1;
+			WSLUA_RETURN(1); /* the unsigned integer value */
             /*
              * XXX:
              *    lua uses double so we have 52 bits to play with
@@ -580,7 +603,9 @@ static int TvbRange_get_uint(lua_State* L) {
 /*
  *  get a Lilliputian unsigned integer from a tvb
  */
-static int TvbRange_get_le_uint(lua_State* L) {
+WSLUA_METHOD TvbRange_get_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.
+	There's no support yet for 64 bit integers*/
     TvbRange tvbr = checkTvbRange(L,1);
     if (!tvbr) return 0;
     
@@ -597,7 +622,7 @@ static int TvbRange_get_le_uint(lua_State* L) {
             return 1;
         case 4:
             lua_pushnumber(L,tvb_get_letohl(tvbr->tvb,tvbr->offset));
-            return 1;
+			WSLUA_RETURN(1); /* the unsigned integer value */
         default:
             luaL_error(L,"TvbRange:get_le_uint() does not handle %d byte integers",tvbr->len);
             return 0;
@@ -607,7 +632,8 @@ static int TvbRange_get_le_uint(lua_State* L) {
 /*
  *  get a Blefuscuoan float
  */
-static int TvbRange_get_float(lua_State* L) {
+WSLUA_METHOD TvbRange_get_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. */
     TvbRange tvbr = checkTvbRange(L,1);
     if (!tvbr) return 0;
     
@@ -617,7 +643,7 @@ static int TvbRange_get_float(lua_State* L) {
             return 1;
         case 8:
             lua_pushnumber(L,tvb_get_ntohieee_double(tvbr->tvb,tvbr->offset));
-            return 1;
+			WSLUA_RETURN(1); /* the flaoting point value */
         default:
             luaL_error(L,"TvbRange:get_float() does not handle %d byte floating numbers",tvbr->len);
             return 0;
@@ -627,7 +653,8 @@ static int TvbRange_get_float(lua_State* L) {
 /*
  * get a Lilliputian float
  */
-static int TvbRange_get_le_float(lua_State* L) {
+WSLUA_METHOD TvbRange_get_le_float(lua_State* L) {
+	/* 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) return 0;
     
@@ -637,20 +664,25 @@ static int TvbRange_get_le_float(lua_State* L) {
             return 1;
         case 8:
             lua_pushnumber(L,tvb_get_letohieee_double(tvbr->tvb,tvbr->offset));
-            return 1;
+			WSLUA_RETURN(1); /* the flaoting point value */
         default:
             luaL_error(L,"TvbRange:get_float() does not handle %d byte floating numbers",tvbr->len);
             return 0;
     }
 }
 
-static int TvbRange_get_ipv4(lua_State* L) {
+WSLUA_METHOD TvbRange_get_ipv4(lua_State* L) {
+	/* get an IPv4 Address from a TvbRange. */
+
     TvbRange tvbr = checkTvbRange(L,1);
     Address addr;
     guint32* ip_addr;
     
     if ( !tvbr ) return 0;
     
+	if (tvbr->len != 4) 
+		WSLUA_ERROR(TvbRange_get_ipv4,"The range must be 4 octets long");
+	
     addr = g_malloc(sizeof(address));
 
     ip_addr = g_malloc(sizeof(guint32));
@@ -659,10 +691,11 @@ static int TvbRange_get_ipv4(lua_State* L) {
     SET_ADDRESS(addr, AT_IPv4, 4, ip_addr); 
     pushAddress(L,addr);
 
-    return 1;
+	WSLUA_RETURN(1); /* the IPv4 Address */
 }
 
-static int TvbRange_get_ether(lua_State* L) {
+WSLUA_METHOD TvbRange_get_ether(lua_State* L) {
+	/* get an Ethernet Address from a TvbRange. */
     TvbRange tvbr = checkTvbRange(L,1);
     Address addr;
     guint8* buff;
@@ -671,26 +704,31 @@ static int TvbRange_get_ether(lua_State* L) {
     
     addr = g_malloc(sizeof(address));
     
+	if (tvbr->len != 6)
+		WSLUA_ERROR(TvbRange_get_ether,"The range must be 6 bytes long");
+	
     buff = tvb_memdup(tvbr->tvb,tvbr->offset,tvbr->len);
     
     SET_ADDRESS(addr, AT_ETHER, 6, buff); 
     pushAddress(L,addr);
     
-    return 1;    
+	WSLUA_RETURN(1); /* the Ethernet Address */
 }
 
 
-static int TvbRange_get_string(lua_State* L) {
+WSLUA_METHOD TvbRange_get_string(lua_State* L) {
+	/* obtain a string from a TvbRange */
     TvbRange tvbr = checkTvbRange(L,1);
     
     if ( !tvbr ) return 0;
     
     lua_pushstring(L, (gchar*)tvb_get_ephemeral_string(tvbr->tvb,tvbr->offset,tvbr->len) );
     
-    return 1;
+	WSLUA_RETURN(1); /* the string */
 }
 
-static int TvbRange_get_bytes(lua_State* L) {
+WSLUA_METHOD TvbRange_get_bytes(lua_State* L) {
+	/* obtain a ByteArray */
     TvbRange tvbr = checkTvbRange(L,1);
     GByteArray* ba;
     
@@ -701,10 +739,13 @@ static int TvbRange_get_bytes(lua_State* L) {
     
     pushByteArray(L,ba);
     
-    return 1;
+	WSLUA_RETURN(1); /* the ByteArray */
 }
 
-static int TvbRange_tostring(lua_State* L) {
+WSLUA_METAMETHOD TvbRange__tostring(lua_State* L) {
+	/* 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);
 
     if (!tvbr) return 0;
@@ -729,7 +770,7 @@ static const luaL_reg TvbRange_methods[] = {
 static const luaL_reg TvbRange_meta[] = {
     {"__index", TvbRange_get_index},
     {"__newindex", TvbRange_set_index},
-    {"__tostring", TvbRange_tostring},
+    {"__tostring", TvbRange__tostring},
     {0, 0}
 };
 
diff --git a/epan/wslua/wslua_util.c b/epan/wslua/wslua_util.c
index 49e3d5d1a5..a116dc27ae 100644
--- a/epan/wslua/wslua_util.c
+++ b/epan/wslua/wslua_util.c
@@ -24,7 +24,7 @@
  * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
  */
 
-/* WSLUA_MODULE Util various useful functions */
+/* WSLUA_MODULE Utility Utility Functions */
 
 #include "wslua.h"
 #include <math.h>
@@ -69,7 +69,7 @@ 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 an absolute timestamp in a human readable form */
+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 time = luaL_checknumber(LS,WSLUA_ARG_format_time_TIMESTAMP);
 	nstime_t then;
@@ -162,6 +162,8 @@ const char* 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
 	const char *given_fname = luaL_checkstring(L, WSLUA_ARG_loadfile_FILENAME);
 	const char* filename;
@@ -180,6 +182,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
 	const char *given_fname = luaL_checkstring(L, WSLUA_ARG_dofile_FILENAME);
 	const char* filename;
@@ -199,29 +203,30 @@ WSLUA_FUNCTION wslua_dofile(lua_State* L) {
 
 
 WSLUA_FUNCTION wslua_persconffile_path(lua_State* L) {
-#define WSLUA_OPTARG_persconffile_path_FILENAME 1
+#define WSLUA_OPTARG_persconffile_path_FILENAME 1 /* a filename */
 	const char *fname = luaL_optstring(L, WSLUA_OPTARG_persconffile_path_FILENAME,"");
 	const char* filename = get_persconffile_path(fname,FALSE);
 	
 	lua_pushstring(L,filename);
-	return 1;
+	WSLUA_RETURN(1); /* the full pathname for a file in the personal configuration directory */
 }
 
 WSLUA_FUNCTION wslua_datafile_path(lua_State* L) {
-#define WSLUA_OPTARG_datafile_path_FILENAME 1
+#define WSLUA_OPTARG_datafile_path_FILENAME 1 /* a filename */
 	const char *fname = luaL_optstring(L, WSLUA_OPTARG_datafile_path_FILENAME,"");
 	const char* filename = get_datafile_path(fname);
 
 	lua_pushstring(L,filename);
-	return 1;
+	WSLUA_RETURN(1); /* the full pathname for a file in wireshark's configuration directory */
 }
 
 
 WSLUA_CLASS_DEFINE(Dir,NOP,NOP); /* A Directory */
 
-WSLUA_CONSTRUCTOR wslua_Dir_open(lua_State* L) {
-#define WSLUA_ARG_Dir_open_PATHNAME 1
-#define WSLUA_OPTARG_Dir_open_EXTENSION 2
+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 */
 	
 	const char* dirname = luaL_checkstring(L,WSLUA_ARG_Dir_open_PATHNAME);
 	const char* extension = luaL_optstring(L,WSLUA_OPTARG_Dir_open_EXTENSION,NULL);
@@ -249,18 +254,19 @@ WSLUA_CONSTRUCTOR wslua_Dir_open(lua_State* L) {
 	}
 	
 	pushDir(L,dir);
-	return 1;
+	WSLUA_RETURN(1); /* the Dir object */
 }
 
-WSLUA_METAMETHOD wslua_Dir__call(lua_State* L) {
-#define WSLUA_ARG_Dir__call_DIR 1
+WSLUA_METAMETHOD Dir__call(lua_State* L) {
+/* at every invocation will return one file (nil when done) */
+
 	Dir dir = checkDir(L,1);
 	const FILE_T* file;
 	const gchar* filename;
 	const char* ext;
 	
 	if (!dir) 
-		WSLUA_ARG_ERROR(Dir__call,DIR,"must be a Dir");
+		luaL_argerror(L,1,"must be a Dir");
 
 	if (!dir->dir) {
 		return 0;
@@ -295,8 +301,8 @@ WSLUA_METAMETHOD wslua_Dir__call(lua_State* L) {
 	return 0;
 }
 
-WSLUA_METHOD wslua_Dir_close(lua_State* L) {
-#define WSLUA_ARG_Dir_close_DIR 1
+WSLUA_METHOD Dir_close(lua_State* L) {
+/* closes the directory */
 	Dir dir = checkDir(L,1);
 
 	if (dir->dir) {
@@ -308,7 +314,6 @@ WSLUA_METHOD wslua_Dir_close(lua_State* L) {
 }
 
 WSLUA_METAMETHOD wslua_Dir__gc(lua_State* L) {
-#define WSLUA_ARG_Dir__gc_DIR 1
 	Dir dir = checkDir(L,1);
 	
 	if (dir->dir) {
@@ -327,13 +332,13 @@ WSLUA_METAMETHOD wslua_Dir__gc(lua_State* L) {
 }
 
 static const luaL_reg Dir_methods[] = {
-    {"open", wslua_Dir_open},
-    {"close", wslua_Dir_close},
+    {"open", Dir_open},
+    {"close", Dir_close},
     {0, 0}
 };
 
 static const luaL_reg Dir_meta[] = {
-    {"__call", wslua_Dir__call},
+    {"__call", Dir__call},
     {"__gc", wslua_Dir__gc},
     {0, 0}
 };