Re: Minutes of the GTK+ Team IRC meeting - 2008-05-13

[Emmanuele Bassi <ebassi gmail com>]

On Wed, 2008-05-14 at 22:15 +0300, Stefan Kost wrote:

> > * rework the gobject tutorial
> > - it is old and unmaintained
> > - the signals section is broken
> > - teaches bad practises
> 
> I can go over it. Please send me pointers to what you want to have changed. From 
> my own todo list:

- the signals section is wrong on various levels that should require a
complete rewrite.

- storing signal ids inside the class structure is wrong; if a subclass
needs to emit a signal defined by its parent class, then it should call
g_signal_emit_by_name().

- the example of using signals to write a buffer to disk is utterly
wrong; it's a nice way of demonstrating overriding a virtual function,
not of using signals.

- the examples are inconsistent in the coding style, with obvious errors
due to copy and pasting from different sources. and please, let's drop
the MAMAN thing: only french-speaking people will get the reference; for
everyone else it's not different than calling the classes 'foo' and
'bar' - which, at least, would be an inside joke.

- the tutorial contains personal remarks that don't belong to a text
distributed with the library.

- the section about GTypeInstance should either be dropped or
incorporated into the GTypeInstance page of the API reference; as it is,
it just confuses readers.

- the private data section should be removed, and only
g_type_class_add_private() should be used to illustrate the private
pointer.

- the section about potential "abuses" of the signals is wrong; if we
are scare of potential "abuses" we should not put this information
inside the tutorial, but inside the API reference. the section does talk
about signal emission hooks and blocking, though; hence it's not abusing
anything.

- the tutorial references sources files that are not shipped with GLib.

- the dispose implementation is horrid, and there's no finalize example.

I already have a patch fixing some of the inconsistencies attached here:

  http://bugzilla.gnome.org/show_bug.cgi?id=530759

> * G_DEFINE_TYPE and the like could be added (although I dislike their limmitations)

using G_DEFINE_TYPE() at least avoids having non mt-safe GType
functions, for instance, unless you want to periodically not only
recompile, but rewrite them. let's face it: writing a get_type()
function is needed only for interfaces - and I'd really like to avoid
that as well with a G_DEFINE_INTERFACE macro. otherwise is just a huge
waste of time.

> Speaking of docs. Whats the opinion of gtk/glib developers regarding inline 
> api-docs. I am much in favour of them. If the core developers are for it, we 
> could do a joint effort and move the docs. I did that once for gstreamer. 
> Unfortunately glib/gdk/gtk/gtk-pixbuf is too much for one person.

AFAIR, most of the gtk+ team is in favour of slowly moving away from
template files and use inlined gtk-doc. the task is daunting, and would
probably be a good chance to audit and improve (or correct) the current
documentation as well. personally, I feel that it's something that
should be tackled on a per-template file basis; even new contributors
could start doing this.

> Stefan
> > 
> > irc log available at: http://live.gnome.org/GTK+/Meetings
> > next meeting: 2008-05-27, 20:00 UTC
> > 
> > ciao,
> >  Emmanuele.
> > 
> 
-- 
Emmanuele Bassi,
W: http://www.emmanuelebassi.net
B: http://log.emmanuelebassi.net