r10829: Documentation updates

Update TODO
Some small fixes to the modules
(This used to be commit 0c53e7c3cf7fd91fd34c48a5e68c1bcf70569854)

6 files changed, 158 insertions, 26 deletions

diff --git a/source4/pidl/lib/Parse/Pidl/Dump.pm b/source4/pidl/lib/Parse/Pidl/Dump.pm
index 80219a8f1a..3a1cec1b59 100644
--- a/source4/pidl/lib/Parse/Pidl/Dump.pm
+++ b/source4/pidl/lib/Parse/Pidl/Dump.pm
@@ -1,8 +1,22 @@
 ###################################################
 # dump function for IDL structures
 # Copyright tridge@samba.org 2000
+# Copyright jelmer@samba.org 2005
 # released under the GNU GPL
 
+=pod
+
+=head1 NAME
+
+Parse::Pidl::Dump - Dump support
+
+=head1 DESCRIPTION
+
+This module provides functions that can generate IDL code from 
+internal pidl data structures.
+
+=cut
+
 package Parse::Pidl::Dump;
 
 use Exporter;
diff --git a/source4/pidl/lib/Parse/Pidl/Ethereal/Conformance.pm b/source4/pidl/lib/Parse/Pidl/Ethereal/Conformance.pm
index 706a259306..1b550ae1e7 100644
--- a/source4/pidl/lib/Parse/Pidl/Ethereal/Conformance.pm
+++ b/source4/pidl/lib/Parse/Pidl/Ethereal/Conformance.pm
@@ -3,6 +3,81 @@
 # Copyright jelmer@samba.org 2005
 # released under the GNU GPL
 
+=pod
+
+=head1 NAME
+
+Parse::Pidl::Ethereal::Conformance - Conformance file parser for Ethereal
+
+=head1 DESCRIPTION
+
+This module supports parsing Ethereal conformance files (*.cnf).
+
+=head1 FILE FORMAT
+
+Pidl needs additional data for ethereal output. This data is read from 
+so-called conformance files. This section describes the format of these 
+files.
+
+Conformance files are simple text files with a single command on each line.
+Empty lines and lines starting with a '#' character are ignored.
+Arguments to commands are seperated by spaces.
+
+The following commands are currently supported:
+
+=over 4
+
+=item I<TYPE> name dissector ft_type base_type mask valsstring alignment
+
+Register new data type with specified name, what dissector function to call 
+and what properties to give header fields for elements of this type.
+
+=item I<NOEMIT> type
+
+Suppress emitting a dissect_type function for the specified type
+
+=item I<PARAM_VALUE> type param
+
+Set parameter to specify to dissector function for given type.
+
+=item I<HF_FIELD> hf title filter ft_type base_type valsstring mask description
+
+Generate a custom header field with specified properties.
+
+=item I<HF_RENAME> old_hf_name new_hf_name
+
+Force the use of new_hf_name when the parser generator was going to 
+use old_hf_name.
+
+This can be used in conjunction with HF_FIELD in order to make more then 
+one element use the same filter name.
+
+=item I<STRIP_PREFIX> prefix
+
+Remove the specified prefix from all function names (if present).
+	
+=item I<PROTOCOL> longname shortname filtername
+
+Change the short-, long- and filter-name for the current interface in
+Ethereal.
+
+=item I<FIELD_DESCRIPTION> field desc
+
+Change description for the specified header field. `field' is the hf name of the field.
+
+=item I<IMPORT> dissector code...
+
+Code to insert when generating the specified dissector. @HF@ and 
+@PARAM@ will be substituted.
+
+=back
+
+=head1 EXAMPLE
+
+	INFO_KEY OpenKey.Ke
+
+=cut
+
 package Parse::Pidl::Ethereal::Conformance;
 
 require Exporter;
diff --git a/source4/pidl/lib/Parse/Pidl/Ethereal/NDR.pm b/source4/pidl/lib/Parse/Pidl/Ethereal/NDR.pm
index be542638ef..8a4c0ed60c 100644
--- a/source4/pidl/lib/Parse/Pidl/Ethereal/NDR.pm
+++ b/source4/pidl/lib/Parse/Pidl/Ethereal/NDR.pm
@@ -6,6 +6,14 @@
 # Portions based on idl2eth.c by Ronnie Sahlberg
 # released under the GNU GPL
 
+=pod
+
+=head1 NAME
+
+Parse::Pidl::Ethereal::NDR - Parser generator for Ethereal
+
+=cut
+
 package Parse::Pidl::Ethereal::NDR;
 
 use strict;
diff --git a/source4/pidl/lib/Parse/Pidl/NDR.pm b/source4/pidl/lib/Parse/Pidl/NDR.pm
index 64190e87b8..f975e07b15 100644
--- a/source4/pidl/lib/Parse/Pidl/NDR.pm
+++ b/source4/pidl/lib/Parse/Pidl/NDR.pm
@@ -5,6 +5,26 @@
 # Copyright jelmer@samba.org 2004-2005
 # released under the GNU GPL
 
+=pod
+
+=head1 NAME
+
+Parse::Pidl::NDR - NDR parsing information generator
+
+=head1 DESCRIPTION
+
+#####################################################################
+# return a table describing the order in which the parts of an element
+# should be parsed
+# Possible level types:
+#  - POINTER
+#  - ARRAY
+#  - SUBCONTEXT
+#  - SWITCH
+#  - DATA
+
+=cut
+
 package Parse::Pidl::NDR;
 
 require Exporter;
@@ -62,15 +82,6 @@ sub fatal($$)
 	die("$pos->{FILE}:$pos->{LINE}:$s\n");
 }
 
-#####################################################################
-# return a table describing the order in which the parts of an element
-# should be parsed
-# Possible level types:
-#  - POINTER
-#  - ARRAY
-#  - SUBCONTEXT
-#  - SWITCH
-#  - DATA
 sub GetElementLevelTable($)
 {
 	my $e = shift;
@@ -394,6 +405,7 @@ sub ParseUnion($)
 
 	if (has_property($e, "nodiscriminant")) { $switch_type = undef; }
 	
+	my $hasdefault = 0;
 	foreach my $x (@{$e->{ELEMENTS}}) 
 	{
 		my $t;
@@ -404,6 +416,7 @@ sub ParseUnion($)
 		}
 		if (has_property($x, "default")) {
 			$t->{CASE} = "default";
+			$hasdefault = 1;
 		} elsif (defined($x->{PROPERTIES}->{case})) {
 			$t->{CASE} = "case $x->{PROPERTIES}->{case}";
 		} else {
@@ -417,6 +430,7 @@ sub ParseUnion($)
 		SWITCH_TYPE => $switch_type,
 		ELEMENTS => \@elements,
 		PROPERTIES => $e->{PROPERTIES},
+		HAS_DEFAULT => $hasdefault,
 		ORIGINAL => $e
 	};
 }
diff --git a/source4/pidl/lib/Parse/Pidl/Samba3/Header.pm b/source4/pidl/lib/Parse/Pidl/Samba3/Header.pm
index 78bd8fe339..25102e511a 100644
--- a/source4/pidl/lib/Parse/Pidl/Samba3/Header.pm
+++ b/source4/pidl/lib/Parse/Pidl/Samba3/Header.pm
@@ -31,7 +31,6 @@ sub ParseElement($)
 			return if ($l->{POINTER_TYPE} eq "ref" and $l->{LEVEL} eq "top");
 			pidl "\tuint32 ptr$l->{POINTER_INDEX}_$e->{NAME};";
 		} elsif ($l->{TYPE} eq "SWITCH") {
-			pidl "\tuint32 level_$e->{NAME};";
 		} elsif ($l->{TYPE} eq "DATA") {
 			pidl "\t" . DeclShort($e) . ";";
 		} elsif ($l->{TYPE} eq "ARRAY") {
@@ -106,30 +105,28 @@ sub ParseUnion($$$)
 
 	my $extra = {};
 	
-	unless (has_property($u, "nodiscriminant")) {
-		$extra->{switch_value} = 1;
-	}
+	$extra->{switch_value} = $u->{SWITCH_TYPE};
 
 	foreach my $e (@{$u->{ELEMENTS}}) {
 		foreach my $l (@{$e->{LEVELS}}) {
 			if ($l->{TYPE} eq "ARRAY") {
 				if ($l->{IS_CONFORMANT}) {
-					$extra->{"size"} = 1;
+					$extra->{"size"} = "uint32";
 				}
 				if ($l->{IS_VARYING}) {
-					$extra->{"length"} = $extra->{"offset"} = 1;
+					$extra->{"length"} = $extra->{"offset"} = "uint32";
 				}
 			} elsif ($l->{TYPE} eq "POINTER") {
-				$extra->{"ptr$l->{POINTER_INDEX}"} = 1;
+				$extra->{"ptr$l->{POINTER_INDEX}"} = "uint32";
 			} elsif ($l->{TYPE} eq "SWITCH") {
-				$extra->{"level"} = 1;
+				$extra->{"level"} = "uint32";
 			}
 		}
 	}
 
 	pidl "typedef struct $if->{NAME}_$n\_ctr {";
 	indent;
-	pidl "uint32 $_;" foreach (keys %$extra);
+	pidl "$extra->{$_} $_;" foreach (keys %$extra);
 	pidl "union $if->{NAME}_$n {";
 	indent;
 	foreach (@{$u->{ELEMENTS}}) {
diff --git a/source4/pidl/lib/Parse/Pidl/Samba3/Parser.pm b/source4/pidl/lib/Parse/Pidl/Samba3/Parser.pm
index eaab50b553..c6cc188391 100644
--- a/source4/pidl/lib/Parse/Pidl/Samba3/Parser.pm
+++ b/source4/pidl/lib/Parse/Pidl/Samba3/Parser.pm
@@ -75,8 +75,18 @@ sub ParseElementLevelData($$$$$$$)
 
 	# See if we need to add a level argument because we're parsing a union
 	foreach (@{$e->{LEVELS}}) {
-		push (@args, ParseExpr("level_$e->{NAME}", $env)) 
-			if ($_->{TYPE} eq "SWITCH");
+		next unless ($_->{TYPE} eq "SWITCH");
+		my $t = getType($l->{DATA_TYPE});
+
+		# Set 0 here because one of the variables referenced in SWITCH_IS 
+		# might be an in variable while this one is [out]
+		if (grep(/in/, @{$e->{DIRECTION}}) or 
+			not defined($t) or 
+			has_property($t->{DATA}, "nodiscriminant")) {
+			push (@args, ParseExpr($_->{SWITCH_IS}, $env));
+		} else {
+			push (@args, -1);
+		}	
 	}
 
 	my $c = DissectType(@args);
@@ -263,7 +273,6 @@ sub GenerateEnvElement($$)
 		} elsif ($l->{TYPE} eq "POINTER") {
 			$env->{"ptr$l->{POINTER_INDEX}_$e->{NAME}"} = "v->ptr$l->{POINTER_INDEX}_$e->{NAME}";
 		} elsif ($l->{TYPE} eq "SWITCH") {
-			$env->{"level_$e->{NAME}"} = "v->level_$e->{NAME}";
 		} elsif ($l->{TYPE} eq "ARRAY") {
 			$env->{"length_$e->{NAME}"} = "v->length_$e->{NAME}";
 			$env->{"size_$e->{NAME}"} = "v->size_$e->{NAME}";
@@ -368,7 +377,6 @@ sub UnionGenerateEnvElement($)
 		} elsif ($l->{TYPE} eq "POINTER") {
 			$env->{"ptr$l->{POINTER_INDEX}_$e->{NAME}"} = "v->ptr$l->{POINTER_INDEX}";
 		} elsif ($l->{TYPE} eq "SWITCH") {
-			$env->{"level_$e->{NAME}"} = "v->level";
 		} elsif ($l->{TYPE} eq "ARRAY") {
 			$env->{"length_$e->{NAME}"} = "v->length";
 			$env->{"size_$e->{NAME}"} = "v->size";
@@ -394,15 +402,20 @@ sub ParseUnion($$$)
 	indent;
 	DeclareArrayVariables($u->{ELEMENTS});
 
-	unless (has_property($u, "nodiscriminant")) {
-		pidl "if (!prs_uint32(\"switch_value\", ps, depth, &v->switch_value))";
+	if (defined ($u->{SWITCH_TYPE})) {
+		pidl "if (MARSHALLING(ps)) ";
+		pidl "\tv->switch_value = level;";
+		pidl "";
+		pidl "if (!prs_$u->{SWITCH_TYPE}(\"switch_value\", ps, depth, &v->switch_value))";
 		pidl "\treturn False;";
 		pidl "";
+	} else {
+		pidl "v->switch_value = level;";
 	}
 
 	# Maybe check here that level and v->switch_value are equal?
 
-	pidl "switch (level) {";
+	pidl "switch (v->switch_value) {";
 	indent;
 
 	foreach (@{$u->{ELEMENTS}}) {
@@ -420,19 +433,30 @@ sub ParseUnion($$$)
 		pidl "";
 	}
 
+	unless ($u->{HAS_DEFAULT}) {
+		pidl "default:";
+		pidl "\treturn False;";
+		pidl "";
+	}
+
 	deindent;
 	pidl "}";
 	pidl "";
 	pidl "return True;";
 	deindent;
 	pidl "}";
+	pidl "";
 
 	pidl "BOOL $dfn(const char *desc, $sn* v, uint32 level, prs_struct *ps, int depth)";
 	pidl "{";
 	indent;
 	DeclareArrayVariables($u->{ELEMENTS});
 
-	pidl "switch (level) {";
+	if (defined($u->{SWITCH_TYPE})) {
+		pidl "switch (v->switch_value) {";
+	} else {
+		pidl "switch (level) {";
+	}
 	indent;
 
 	foreach (@{$u->{ELEMENTS}}) {