Re: pre-summit introspection status

["Gustavo J. A. M. Carneiro" <gjc inescporto pt>]

On Thu, 2008-10-09 at 21:34 -0400, Behdad Esfahbod wrote:
> Colin Walters wrote:
> > For those not tracking Planet, here's a pre-summit status report on
> > introspection:
> > 
> > http://cgwalters.livejournal.com/21209.html
> > 
> > Feedback I think would be most helpful is on the annotation syntax,
> > and more eyes checking coverage in gir-repository and filing bugs for
> > the things we're doing wrong.
> 
> I have a comment on annotation syntax.  I don't like that the annotations are
> in comments.  In Berlin I suggested to Johan that something like Qt's "slots"
> trick can be used.  That is, preprocessor macros that normally expand to
> nothing, but the scanner defines them to something special.  Then one could do
> things like:
> 
> /**
>  * gtk_list_store_set_column_types:
>  * @store: a #GtkListStore
>  * @n_columns:
>  * @types: <array,length=n_columns>: List of types
>  */
> void
> gtk_list_store_set_column_types (GtkListStore *list_store,
>                                  gint          n_columns,
>                                  GType        *types G_IR_ARRAY
> G_IR_ARRAY_LENGTH(n_columns));
> 
> 
> 
> Johan didn't see any immediate benefit in that and suggested that it makes for
> a worse syntax and formatting, and I agreed.
> 
> But most recently I was reading the static analysis literature and came across
> the idea of using gcc user-attributes for source code annotation.  Take the
> above example, then one can define:
> 
> #define G_IR_ARRAY __attribute__((user(g_ir_array)))
> 
> On the face, it's not much different from what I proposed earlier.  However,
> it has an immense power: you can use gcc or gcc-compatible frontends.
> Moreover, you can write static analyzers that check, for example, that the
> array is not shorter than its claimed length.  The possibilities are uncountable.
> 
> If you don't like the syntax, it can be done on the prototype like, much like
> G_GNUC_PRINTF stuff:
> 
> void gtk_list_store_set_column_types (GtkListStore *list_store,
>                                       gint          n_columns,
>                                       GType        *types)
> G_IR_ARRAY(types, n_columns);
> 
> So, here I am proposing it.  Recently some guys at Google used that format for
> thread-safety static analysis.  See:
> 
>   https://docs.google.com/View?docid=ddqtfwhb_0c49t6zgr
> 
> 

Personally, I think we should use whatever is easiest to parse, not what
is more sexy.  As far as I can tell, the __attribute__ stuff is only
easier to parse if you use something like GCC-XML (with its associated
problems) to parse the header files.  Otherwise the current gtk-doc
syntax appears to me much simpler to parse for a simple
python/perl/whatever script.

-- 
Gustavo J. A. M. Carneiro
<gjc inescporto pt> <gustavo users sourceforge net>
"The universe is always one step beyond logic" -- Frank Herbert