Allowing docbook markup in inline docs

["Matthias Clasen" <matthiasc poet de>]

The patch below against gtk-doc-0.7 implements a variant of doc comments
starting with ' /*** ' instead of ' /** ' which pass SGML markup unescaped,
so that we can use <function>, <filename> and all the nice docbook markup
in order to get properly formatted docs from doc comments.


Matthias

--- gtk-doc-0.7/gtkdoc-mkdb.in	Sat Aug  4 22:40:14 2001
+++ gtk-doc-0.7.patched/gtkdoc-mkdb.in	Tue Sep 25 15:25:02 2001
@@ -840,7 +840,7 @@
 	    }

 	    # allow alphanumerics, '_', '[' & ']' in param names
-	} elsif ($declaration =~
s/^(const\s+|unsigned\s+)*(struct\s+)?((?:long\s+|short\s+)?\w+)\s*(\**)\s*(
const\s+)?(\**)?\s*(\w+)?\s*((?:\[\S*\])*)\s*[,\n]//) {
+	} elsif ($declaration =~
s/^(const\s+|G_CONST_RETURN\s+|unsigned\s+)*(struct\s+)?((?:long\s+|short\s+
)?\w+)\s*(\**)\s*(const\s+)?(\**)?\s*(\w+)?\s*((?:\[\S*\])*)\s*[,\n]//) {
 	    my $mod1 = defined($1) ? $1 : "";
 	    if (defined($2)) { $mod1 .= $2; }
 	    my $type = $3;
@@ -1597,6 +1597,7 @@
     open (SRCFILE, $file)
 	|| die "Can't open $file: $!";
     my $in_comment_block = 0;
+    my $pass_sgml = "";
     my $symbol;
     my ($in_description, $in_return);
     my ($description, $return_desc, $return_start);
@@ -1607,7 +1608,8 @@
 	if (!$in_comment_block) {
 	    if (m%^\s*/\*.*\*/%) {
 	        #one-line comment - not gtkdoc
-	    } elsif (m%^\s*/\*\*\s%) {
+	    } elsif (m%^\s*/\*\*(\*?)\s%) {
+	        $pass_sgml = $1;
 #		print "Found comment block start\n";
 		$in_comment_block = 1;

@@ -1637,6 +1639,18 @@
 		    push (@params, "Returns");
 		    push (@params, $return_desc);
 		}
+                # Convert special SGML characters. I'm not sure if we want
to
+		# do this but currently there are a couple of '&'s in the
+                # source code comment blocks which mess up the HTML output
+                # badly.
+		if (!$pass_sgml) {
+	             $description = &CreateValidSGML ($description);
+		     my $k;
+      		     for ($k = 1; $k <= $#params; $k += 2) {
+		        $params[$k] = &CreateValidSGML ($params[$k]);
+		      }
+		   }
+
 		$SourceSymbolDocs{$symbol} = $description;
 		$SourceSymbolParams{$symbol} = [ @params ];
 	    }
@@ -1826,11 +1840,6 @@
                  $AllDocumentedSymbols{$symbol} = 1;
             }

-	    # Convert special SGML characters. I'm not sure if we want to do
-	    # this but currently there are a couple of '&'s in the source code
-	    # comment blocks which mess up the HTML output badly.
-	    $src_doc = &CreateValidSGML ($src_doc);
-
 	    # If there is a blank line, finish the paragraph and start another.
 	    if ($src_doc =~ s%\n{2,}%\n</para>\n<para>\n%g) {
 #		print "Converted blank lines:\n$src_doc\n";
@@ -1863,7 +1872,7 @@
 			$found = 1;

 			# Override the description.
-			$$tmpl_params[$j + 1] = &CreateValidSGML ($param_desc);
+			$$tmpl_params[$j + 1] = $param_desc;

 			# Set the name to "" to mark it as used.
 			$$params[$k] = "";