Re: gtk_builder_add_from_file error handling

[Emmanuele Bassi <ebassi gmail com>]

On Wed, 2010-01-13 at 17:18 +0100, Gabriele Greco wrote:
> > The proper handling of GErrors is described in great detail in the
> > GError documentation.
> >
> > I don't think it is reasonable to explain this in the documentation of
> > every function that uses GError to report errors as there are almost 80
> > of them just in Gtk+ (and over 400 in GLib, and many more elsewhere).
> I think, and I'm used to see in almost every framework documentations, that
> every time a function allocates something that the API user must free
> himself the documentation should explicitly say so. Documentation should be
> redundant when it may cause errors the fact it is not.

that's why gtk-doc creates cross-links for each data type.

> This is the case of GError and for
> instance gtk_ui_manager_add_ui_from_file/string
> and gtk_builder_add_from_file/string.
>
> It's not a case that in UI toolkit debates one of the most common criticism
> to GTK is the "lack of documentation".

the "lack of documentation" refers to empty (or FIXME) sections of the
API reference and to high-level documentation. the fact that a non-NULL
GError must be freed using the corresponding GError free function is
documented in great detail and that documentation linked by every
function in a gtk-doc-generated API reference and part of the behavior
of the framework.

the API reference does not gain anything by adding:

  @error: a return location for a #GError or %NULL.
+   Use g_error_free() to free the #GError if @error is not %NULL
+   after calling this function

for each and every GError-using function. you'd just be writing
redundant documentation.

if you can't be bothered to follow through a link then you're probably
using g_free() on every single data structure, which yields
"interesting" results when done on, say, GString or worse GObject.

ciao,
 Emmanuele.

-- 
W: http://www.emmanuelebassi.name
B: http://blogs.gnome.org/ebassi