Re: Scanning for signal prototypes

[James Henstridge <james jamesh id au>]

Roger Leigh wrote:

> -----BEGIN PGP SIGNED MESSAGE-----
> Hash: SHA1
>
> Hi folks,
>
> I've just added gtk-doc support to a new project I'm working on.  The
> code is here:
>
>  http://www.whinlatter.ukfsn.org/gtk/uterm-0.1.0.tar.bz2
>
> I think I've set it up correctly.  I've added the Makefiles, configure
> macro and then set up the .type and sections.txt files.  It works but
> for one thing: the signal prototypes in the docs don't match the
> marshaller or the class method.  For example
> (uterm/uterm-code-table.c):
>
>  table_signals[SIGNAL_CHAR_CHANGED] =
>    g_signal_new ("character-changed",
> 		  G_OBJECT_CLASS_TYPE(klass),
> 		  G_SIGNAL_RUN_FIRST | G_SIGNAL_ACTION,
> 		  G_STRUCT_OFFSET (UtermCodeTableClass, character_changed),
> 		  NULL, NULL,
> 		  g_cclosure_marshal_VOID__UINT,
> 		  G_TYPE_NONE, 0);
>
> and in the header:
>
> struct _UtermCodeTableClass
> {
>  GObjectClass		     parent;
>  void (* character_changed) (UtermCodeTable *table,
> 			      int             index);
>
> };
>
> In the docs, I get this:
>
>  The "character-changed" signal
>
>  void        user_function                  (UtermCodeTable *utermcodetable,
>                                              gpointer user_data);
>
>  utermcodetable :	the object which received the signal.
>  user_data :	user data set when the signal handler was connected.
>
> The uint parameter was missed out!  Do I need to do anything special
> for it to detect the prototype?  I thought this would be detectable
> through the marshaller in use or the virtual class method prototype.
> Can these be documented inline, or only in the templates?
>  
The signal documentation is extracted through the introspection 
interfaces in glib/GTK.  From the code you pasted, it the extracted 
prototype isn't too surprising, since it matches the prototype you gave 
in the g_signal_new() call -- a signal taking 0 additional arguments and 
returning nothing.

If you change the g_signal_new() call to say that the signal takes 1 
uint argument, the documentation should be generated correctly.  You'll 
probably find that the incorrect signal prototype will cause problems in 
code that actually tries to use the signal ...

James.