Re: Signal argument names

[Owen Taylor <otaylor redhat com>]

Matthias Clasen <maclas gmx de> writes:

> > 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 ?). 

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

> Also, I haven't touched the automatic addition of the user_data
> parameter.
> 
> Comments ?

Looks reasonable to me. I don't think the user_data parameter
should have to be documented for each signal, so leaving it 
autogenerated should be fine.

> +			$name = $$sourceparams[2 * $j];

Perl style note:

This is consistent with what is elsewhere, but I'll point
out that 
 
 $sourceparams->[2 * $j]

Is generally the preferred syntax for this these days; it avoids
confusing visual ambiguity over whether the above is
${$sourceparams}[2 * $j] or ${$sourceparams[2 * $j]}.

Regards,
                                        Owen