Re: Signal argument names

[Matthias Clasen <maclas gmx de>]

On Thu, 2002-11-07 at 17:32, Owen Taylor wrote:
> > I have this mostly working, see the attached patch. There are some
> > complications, because we have to be careful to prefer the param names
> > from source over those generated by gtkdoc-scangobj (those pesky argn),
> > unlike normal functions, where we prefer the names from the templates
> > over the source names (why ?). 
> 
> I think the idea is that it won't matter because the template
> file names have to match the names found by gtkdoc-scan, or
> gtkdoc-mktmpl will replace them when updating the template
> files.
> 
> See, OutputParam() in gtkdoc-mktmpl

Yes. Unfortunately, gtkdoc-mktmpl can never get this right for signals,
since it only has the artificially generated arg names from the
gtk.signals file and the stuff already in the templates to choose from.
To fix this, we would probably have to extend gtkdoc-scan to also parse
signal declarations in headers and dump them (with meaningfull arg
names) to gtk-decl.txt. Since this is a bit more work, I have instead
modified gtkdoc-mkdb to prefer the c source arg names over template arg
names (for signals only).
 
Here is a new version of the patch, which additionally supports putting
property documentation inline in the form:

/**
 * GdkDisplayManager:default-display:
 *
 * The default display.
 */

This will then be used instead of the blurb. Note that properties use a
single : instead of :: to separate class and symbol. (I've just copied
existing gtk-doc practice, don't know if it is really necessary -
clashes with signals should be very rare...)

Do you have any proposal for the placement of these signal and property
doc comments in the source ? Before class_init, after class_init, or
even inside class_init, before the corresponding signal/property
registrations ?

Matthias

? diff
? symversions.diff
? cvsup.log
? signal.diff
? patches
? signal+prop.diff
? gtkdoc-scangobj.in.prereq
Index: gtkdoc-mkdb.in
===================================================================
RCS file: /cvs/gnome/gtk-doc/gtkdoc-mkdb.in,v
retrieving revision 1.58
diff -u -b -B -p -r1.58 gtkdoc-mkdb.in
--- gtkdoc-mkdb.in	7 Nov 2002 16:11:53 -0000	1.58
+++ gtkdoc-mkdb.in	7 Nov 2002 20:40:42 -0000
@@ -1698,6 +1698,7 @@ sub GetSignals {
 	    $synop .= "${ret_type_output}user_function      (";
 	    $desc  .= "${ret_type_output}user_function                  (";
 
+	    my $sourceparams = $SourceSymbolParams{$symbol};
 	    my @params = split ("\n", $SignalPrototypes[$i]);
 	    my $j;
 	    for ($j = 0; $j <= $#params; $j++) {
@@ -1705,7 +1706,12 @@ sub GetSignals {
 		if ($params[$j] =~ m/^\s*(\w+)\s*(\**)\s*([\w\[\]]+)\s*$/) {
 		    $type = $1;
 		    $pointer = $2;
+		    if (defined($sourceparams)) {
+			$name = $$sourceparams[2 * $j];
+		    }
+		    else {
 		    $name = $3;
+		    }
 		    $xref = &MakeXRef ($type);
 		    $synop .= "$xref $pointer$name,\n";
 		    $synop .= (' ' x ($SYMBOL_FIELD_WIDTH + $RETURN_TYPE_FIELD_WIDTH));
@@ -1790,12 +1796,18 @@ sub GetArgs {
 		$flags_string .= "Construct Only";
 	    }
 
-	    my $blurb = &CreateValidSGML ($ArgBlurbs[$i]);
+	    my $blurb;
+	    if (defined($SymbolDocs{$symbol})) {
+		$blurb = $SymbolDocs{$symbol};
+	    }
+	    else {
+		$blurb = "<para>" . &CreateValidSGML ($ArgBlurbs[$i]) . "</para>";
+	    }
 	    my $pad1 = " " x (20 - length ($name));
 	    my $pad2 = " " x (20 - length ($type));
 
  	    my $arg_synop = "  &quot;<link linkend=\"$id\">$name</link>&quot;$pad1 $type_output$pad2 : $flags_string\n";
-	    my $arg_desc = "<varlistentry><term><anchor id=\"$id\"${empty_element_end}&quot;<literal>$name</literal>&quot; ($type_output : $flags_string)</term>\n<listitem>\n<para>$blurb</para>\n</listitem></varlistentry>\n";
+	    my $arg_desc = "<varlistentry><term><anchor id=\"$id\"${empty_element_end}&quot;<literal>$name</literal>&quot; ($type_output : $flags_string)</term>\n<listitem>\n$blurb\n</listitem></varlistentry>\n";
 
 	    if ($flags =~ m/c/) {
 	        $child_synop .= $arg_synop;
@@ -1944,7 +1956,7 @@ EOF
 
 	# If we haven't found the symbol name yet, look for it.
 	if (!$symbol) {
-	    if (m%^\s*(\w+)\s*:?%) {
+	    if (m%^\s*([\w:-]*\w)\s*:?%) {
 		$symbol = $1;
 	    }
 	    next;
@@ -2143,6 +2155,13 @@ EOF
 	    }
 	    $SymbolDocs{$symbol} = "<para>\n$src_doc</para>\n$tmpl_doc";
 
+	    if ($symbol =~ m/.*::.*/) {
+		# For signals we prefer the param names from the source docs,
+	        # since the ones from the templates are likely to contain the
+	        # artificial argn names which are generated by gtkdoc-scangobj.
+		$SymbolParams{$symbol} = $SourceSymbolParams{$symbol}
+	    }
+	    else {
 	    # The templates contain the definitive parameter names and order,
 	    # so we will not change that. We only override the actual text.
 	    my $tmpl_params = $SymbolParams{$symbol};
@@ -2195,6 +2214,7 @@ EOF
 WARNING: Parameter described in source code comment block but does not exist -
          Func: $symbol Param: $param_name.
 EOF
+		    }
 		}
 	    }
 	} else {
Index: gtkdoc-mktmpl.in
===================================================================
RCS file: /cvs/gnome/gtk-doc/gtkdoc-mktmpl.in,v
retrieving revision 1.25
diff -u -b -B -p -r1.25 gtkdoc-mktmpl.in
--- gtkdoc-mktmpl.in	21 Nov 2001 21:51:43 -0000	1.25
+++ gtkdoc-mktmpl.in	7 Nov 2002 20:40:43 -0000
@@ -642,7 +642,7 @@ sub OutputSignalTemplates {
 $symbol_desc
 
 EOF
-	    
+	    my $sourceparams = $SymbolParams{$symbol};
 	    my @params = split ("[,\n]", $SignalPrototypes[$i]);
 	    my ($j, $name);
 	    for ($j = 0; $j <= $#params; $j++) {
@@ -653,7 +653,10 @@ EOF
 		if ($param =~ m/^void$/) { next; }
 
 		if ($param =~ m/^\s*(\w+)\s*(\**)\s*([\w\[\]]+)?\s*$/) {
-		    if (defined($3)) {
+		    if (defined($sourceparams)) {
+			$name = $$sourceparams[2 * $j];
+		    }
+		    elsif (defined($3)) {
 			$name = $3;
 		    } else {
 			$name = "Param" . ($j + 1);