Re: Signal argument names

[Matthias Clasen <maclas gmx de>]

> It doesn't quite fit in with the way we do things elsewhere, but
> it would be really nice if we could get the argument names from
> the template files or inline docs instead of creating yet
> one more file.
> 
> That is, be able to do in the C file.
> 
> /**
>  * GtkWidget::heirarchy-changed
>  * @widget: the object which received the signal.
>  * @previous_toplevel: The toplevel that was previously
>  *   an ancestor of the widget, or %NULL if the widget
>  *   was previously unanchored.
>  * 
>  * Emitted when there is a chance in the hierarchy to
>  * which a widget belong. More precisely, a widget is
>  * <firstterm>anchored</firstterm> when its toplevel
>  * ancestor is a #GtkWindow. This signal is emitted when 
>  * a widget changes from un-anchored to anchored or vice-versa.
>  **/
> 

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 ?). Also, I haven't touched the automatic
addition of the user_data parameter.

Comments ?

Matthias

Index: gtkdoc-mkdb.in
===================================================================
RCS file: /cvs/gnome/gtk-doc/gtkdoc-mkdb.in,v
retrieving revision 1.57
diff -u -b -B -p -r1.57 gtkdoc-mkdb.in
--- gtkdoc-mkdb.in	19 Oct 2002 23:35:46 -0000	1.57
+++ gtkdoc-mkdb.in	7 Nov 2002 00:55:04 -0000
@@ -1696,6 +1696,7 @@ sub GetSignals {
 	    $synop .= "${ret_type_output}user_function      (";
 	    $desc  .= "${ret_type_output}user_function                  (";
 
+	    my $sourceparams = $SymbolParams{$symbol};
 	    my @params = split ("\n", $SignalPrototypes[$i]);
 	    my $j;
 	    for ($j = 0; $j <= $#params; $j++) {
@@ -1703,7 +1704,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));
@@ -1942,7 +1948,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;
@@ -2354,7 +2360,7 @@ sub ReadSignalsFile {
 		if ($signal_name =~ m/^(.*)::(.*)$/) {
 		    $signal_object = $1;
 		    ($signal_name = $2) =~ s/_/-/g;
-#		    print "Found signal: $signal_name\n";
+		    print "Found signal: $signal_name\n";
 		} else {
 		    print "Invalid signal name: $signal_name\n";
 		}
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 00:55:05 -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);