On Wed, 2005-07-20 at 22:03 +0800, Wang, Yong Y wrote: > Since there are a huge number of functions exported by GTK+ libraries, > including gtk, gdk, glib, gobject, atk and pango, etc, it's impossible > to test them all given the resources we have so far. Therefore we > identified 30 most popular applications built on GTK+, like GIMP and > Evolution, to collect real world data about which set of functions are > most heavily used so that we can begin to work on them first. > > Unfortunely, we found some of the most heavily used functions are not > covered by the existing API documentation. The gtk_*_get_type family > of functions are of this kind, including gtk_container_get_type, > gtk_box_get_type, etc. Are there any reasons why they are > undocumented? The get_type() functions are not individually documented because they are part of the type system rather than (In C code, we typically use the wrapper macro - GTK_TYPE_WIDGET rather than the get_type() function directly.) What a get_type() function does is returns the type ID for a particular class. [...] > But from the existing documentation, we cannot get any success > indicator. The last sentence (i.e. Returns :The new type identifier.) > does not provide such information. I have read the source code of > g_type_register_static and it seems like this function will return 0 > if an error occurred. Is there anyone who can tell whether I > understand correctly or not? In general, for GTK+ (and also for GLib) we try to follow the policy: If a function is called with parameters that are documented to be legal, it will succeed. If a function is called with parameters that are documented to be not legal, than we try to provide diagnostic output when possible, but the behavior of the function is otherwise undefined. To, in essence, define failure out of the equation. So, g_type_register_static() doesn't have a defined error return. If you call it with junk values ... if you say pass 0 as the parent type ID, then it will produce some diagnostic output on standard output and return 0: g_return_val_if_fail (parent_type > 0, 0); This isn't part of the defined contract for the function, and in fact, you can compile GObject to remove the g_return_val_if_fail() checks. It's just there to make things easy on the programmer. While you could certainly test that the result of gtk_widget_get_type() is non-zero, since 0 isn't a legitimate type, probably the more interesting thing to do is to test properties of the type as registered: You could call GTypeQuery on the type and check that class_size == sizeof(GtkWidgetClass) and instance_size == sizeof(GtkWidget). You could check that the super-type (g_type_parent()) You could check that it implements all the interfaces that are expected (g_type_interfaces()) ... you can't check that it implements *only* the interfaces that you expect, since interfaces can be compatibility added in new versions. > Another observation of mine is that the existing documentation always > include a class hierarchy for these types. Let's take GtkContainer as > an example. [...] > >From this hierarchy, we can get the following information: > GtkContainer is a classed type, rather than a fundamental type like > gchar, gint or gdouble, etc. GtkContainer is a derived type (derived > from GtkWidget). GtkContainer is a derivable type. It can be further > derived by GtkBox and GtkTable, etc. The direct parent type of > GtkContainer is GtkWidget. etc. > > The gobject library provides corresponding functions to test these > qualifications as listed below. > > G_TYPE_IS_CLASSED > G_TYPE_IS_DERIVED > G_TYPE_IS_DERIVABLE > g_type_parent > etc. > > Test cases can be developed accordingly. But I'm not sure whether these > qualifications are enough to test these gtk_*_get_type functions. I'm not sure that checking stuff like G_TYPE_IS_CLASSED is going add a lot of information here. If that stuff is wrong, it would indicate problems in the base object system that should be tested in GObject tests, not on objects far down the stack. I'd concentrate more on testing the things that are set up class-by-class.. things like I mentioned above. I should mention that the type hierarchy in the documentation is autogenerated from querying the type system when building the docs. So, if there *are* bugs in how we register the types, then checking against the docs won't reveal them. It could theoretically reveal regressions. Regards, Owen P.S. - I'll note that in general, get_type() functions have not been much of a source of bugs, and almost never a source of regressions. If you write it, and it works, it is likely to continue working.
Attachment:
signature.asc
Description: This is a digitally signed message part