Re: pre-summit introspection status

On Fri, Oct 10, 2008 at 4:17 AM, Gustavo J. A. M. Carneiro <gjc inescporto pt> wrote:
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:
> >
> >
> >
> > 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:

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.

Let's also not forget another use of the gtk-doc annotations: it will allow gtk-doc to present this information in some standard way in the actual documentation. Knowing that something is an array of some length is obviously important for using an API, not just for binding to one.


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

gtk-devel-list mailing list
gtk-devel-list gnome org

[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]