Re: Fourth draft of defs file format

[Havoc Pennington <hp redhat com>]

Miroslav Silovic <silovic@zesoi.fer.hr> writes: 
> Note that this would be a significant change to the current gtk
> codebase (as all the headers would be replaced by autogenerated
> stuff), and if you like this idea, it would certainly have to go in
> before the code freeze. I like this, BTW - it would also force people
> to review their APIs and remove much of the problems (both known
> problems and the ones we have yet to encounter).
>

To autogenerate GTK itself I do think this raises the level of
engineering required for the defs file quite a bit. It is a cleaner
solution but likely a lot more work, too.
 
> ] From Alex Stark:
> ] 
> ] My 2c worth is that provision for very short documentation strings (ie
> ] fewer than 60 chars) could be very useful.
> 
> This would be great for interactive languages like Guile where you can
> request short help for all defined symbols.
>

I'd like to see this in a separate file, especially since translations
would be required. You could just have a simple key-value pair file
with symbols and doc strings.
  
> Note that if the .defs aren't autogenerated but used to create
> headers, this would go "Some definitions can have a c-declaration
> field that gives the C code to be put into the header file."
> 
> Also, C headers obscure more semantic issues than obvious (see below,
> on parametric types), so .defs autogeneration may not be the option in
> many cases (modulo magic comments).
>

Right, the current defs file format draft is going to rely on adding
comments to the GTK headers to autogenerate.
 
> gnome-guile also uses parametric types. For example, if a function
> returns a linked list (in glib sense) of GdkPoints (boxed type), you
> can use (list point) as a parameter. Now these get passed as simple C
> types (but in more than one argument, sometimes) - therefore, the
> definition above is more or less sufficient, with wrapper-dependant
> extensions (defined in a separate file). However, wrapper creation
> would be simpler with some additions:
> 
> (type
>   (doc "Linked list of elements") ; illustrate docstrings
>   (alias list)
>   (allow-parameters) ; specify that this is a compound type
>   (in-c-name "GList*")
>   (out-c-name "GList**")
>   (inout-c-name "Glist**"))
> 
> Then allow use of (list GtkWidget) instead of just list. Wrapper would 
> have to take care of the proper handling of list.
>

Oh, good point. I will try to add something to the format to handle
this; also need to handle the case where you free the returned list,
and the one where you free the list and also its elements.
  
> guile-gtk currently uses the equivalent of (array-size) attribute. The
> other case of paired function arguments are in callbacks (function
> pointer + data) - perhaps one or more callback types would be in
> order.
>

Karl's GClosure thing might help with this long term too.
  
> The one case in gnome-libs that doesn't work well as boxed is
> GnomeHelpMenuEntry, as it seems to be designed for being embedded in C
> static structures. It lacked constructors/destructors/copiers.
> 

Yeah this is probably just a broken API.

Thanks!

Havoc