Re: How to create docs for signal prototypes

[Damon Chaplin <damon ximian com>]

Brian Cameron wrote:
> 
> Gtk-doc experts:
> 
> Another problem that I am having is that when I am trying to build
> my gtk-docs I get these warnings:
> 
> --gtk-doc warning start--
> 
> *** Building SGML ***
> cd . && \
>         gtkdoc-mkdb --module=atk --source-dir=../atk
> Cannot parse structure field G_CONST_RETURN gchar*   (*get_description)
> (AtkAction         *action,
>                                                 gint              i) at
> /sgnome/gnome2.0/sparc-solaris/bin/gtkdoc-mkdb line 2473, <INPUT> chunk 5.
> Cannot parse structure field G_CONST_RETURN gchar*   (*get_keybinding)
> (AtkAction         *action,
>                                                 gint              i) at
> /sgnome/gnome2.0/sparc-solaris/bin/gtkdoc-mkdb line 2473, <INPUT> chunk 5.
> Cannot parse structure field G_CONST_RETURN gchar* ( *get_image_description)
> (AtkImage              *image) at /sgnome/gnome2.0/sparc-solaris/bin/gtkdoc-mkdb
> line 2473, <INPUT> chunk 85.
> 
> --gtk-doc warning end--
> 
> Here is an example of the code that seems to be making it puke:
> 
> --example code start--
> 
> struct _AtkImageIface
> {
>   GTypeInterface parent;
> 
>   G_CONST_RETURN gchar* ( *get_image_description)
>     (AtkImage            *image);
>   void                  ( *get_image_size)
>     (AtkImage            *image,
>      gint                        *height,
>      gint                        *width);
>   gboolean              ( *set_image_description)
>     (AtkImage            *image,
>     const gchar          *description);
> };
> 
> --example code stop--
> 
> It seems to hate the G_CONST_RETURN macro.  How do I fix this?

gtk-doc can only parse a subset of C, so we have to update it occasionally
to handle more complicated things as they appear.

The G_CONST_RETURN thing is probably fairly easy to fix.

This may do it:

diff -u -r1.29 gtkdoc-mkdb.in
--- gtkdoc-mkdb.in	2001/05/25 23:38:57	1.29
+++ gtkdoc-mkdb.in	2001/07/10 01:13:34
@@ -2448,7 +2448,7 @@
 	    
         # Try to match structure members which are functions
 	} elsif ($line =~ m/^
-		 (const\s+|unsigned\s+)*(struct\s+)?  # mod1 
+		 (const\s+|G_CONST_RETURN\s+|unsigned\s+)*(struct\s+)?  # mod1 
 		 (\w+)\s*                             # type
 		 (\**)\s*                             # ptr1
 		 (const\s+)?                          # mod2

I've committed that. (gtkdoc-mktmpl.in already had this fix.)

Damon