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 _______________________________________________ gtk-app-devel-list mailing list gtk-app-devel-list@gnome.org http://mail.gnome.org/mailman/listinfo/gtk-app-devel-list
