Weird exceptions policy in glibmm/giomm

[Tomasz Jankowski]

Hello!

I'm trying to figure out exceptions policy in glibmm/giomm. It's hard
to understand which functions exactly throw exceptions. I made some
research (I read API and source code), but this issue stays still
unclear for me.

As I see there is no exceptions policy for whole project. Some
functions handle exceptions only by returning bool value (example:
Glib::file_test ()).and other return both bool and throw exceptions
(Glib::KeyFile::load_from_file ()). I also found few functions, which
only throws exceptions (Glib::KeyFile::set_comment ()).

I thought that API will explain everything, but it didn't. Example,
description for  Glib::KeyFile::set_comment () doesn't mention, that
function throws exception... Moreover I found some bugs in
documentation, for example  documentation specify return value for
(again...) 'void Glib::KeyFile::set_comment ()'.

I use GTK+ within C++, but some I decided to move to GTKMM to get rid
of C drawbacks and write in pure C++. So far I continue using GTK+...
_______________________________________________
gtkmm-list mailing list
gtkmm-list@...
http://mail.gnome.org/mailman/listinfo/gtkmm-list

[José Alburquerque-3]

On Fri, 2009-07-03 at 20:34 +0200, Tomasz Jankowski wrote:
> Hello!
>
> I'm trying to figure out exceptions policy in glibmm/giomm. It's hard
> to understand which functions exactly throw exceptions. I made some
> research (I read API and source code), but this issue stays still
> unclear for me.

Generally, the docs should say if a function throws an exception or not.
If they don't, the docs need improvement.  Filing a bug (with a patch
possibly) generally takes care of the lack of clarity.

> As I see there is no exceptions policy for whole project. Some
> functions handle exceptions only by returning bool value (example:
> Glib::file_test ()).and other return both bool and throw exceptions
> (Glib::KeyFile::load_from_file ()). I also found few functions, which
> only throws exceptions (Glib::KeyFile::set_comment ()).

Generally, the functions are simply a reflection of the C API.  If the
function in the C API returns a bool, the C++ function will most
probably also return a bool.  Exceptions are generally thrown if the C
function has a a GError output parameter as in
g_key_file_load_from_file[1].

[1]
http://library.gnome.org/devel/glib/2.21/glib-Key-value-file-parser.html#g-key-file-load-from-file

> I thought that API will explain everything, but it didn't. Example,
> description for  Glib::KeyFile::set_comment () doesn't mention, that
> function throws exception... Moreover I found some bugs in
> documentation, for example  documentation specify return value for
> (again...) 'void Glib::KeyFile::set_comment ()'.

Once more, filing a bug will generally inform the maintainers so the
missing information can be added to the docs.  Feel free to file one to
improve the docs.


--
José Alburquerque

_______________________________________________
gtkmm-list mailing list
gtkmm-list@...
http://mail.gnome.org/mailman/listinfo/gtkmm-list

[Daniel Elstner]

Am Freitag, den 03.07.2009, 20:34 +0200 schrieb Tomasz Jankowski:

> I'm trying to figure out exceptions policy in glibmm/giomm. It's hard
> to understand which functions exactly throw exceptions. I made some
> research (I read API and source code), but this issue stays still
> unclear for me.

Nearly all exceptions thrown directly by *mm code are wrapped GError
instances.  If there is a GError in the C API, it will be an exception
in the C++ API.  Normally, the exceptions should be listed in the *mm
documentation as well.  If not, it's a documentation bug.

> As I see there is no exceptions policy for whole project. Some
> functions handle exceptions only by returning bool value (example:
> Glib::file_test ()).and other return both bool and throw exceptions
> (Glib::KeyFile::load_from_file ()).

That's an API bug, but fortunately mostly harmless.  Just ignore the
return value, it will always be true when the function actually returns.

> I also found few functions, which
> only throws exceptions (Glib::KeyFile::set_comment ()).

Yes, that's how it should normally be.  The boolean return value is
redundant and useless in the C++ API.  But the behavior is the same.

> I thought that API will explain everything, but it didn't. Example,
> description for  Glib::KeyFile::set_comment () doesn't mention, that
> function throws exception... Moreover I found some bugs in
> documentation, for example  documentation specify return value for
> (again...) 'void Glib::KeyFile::set_comment ()'.

That's because the documentation is machine-translated from the C
documentation.  This doesn't always work perfectly, in which case we
need to add manual overrides.  Again, this is a documentation bug which
should be filed on bugzilla.gnome.org.  A patch would be great!

> I use GTK+ within C++, but some I decided to move to GTKMM to get rid
> of C drawbacks and write in pure C++. So far I continue using GTK+...

It isn't as bad is it looks at first glance.  The documentation is
flawed, and the examples messy, but the library itself is pretty solid.
We are working on improving the docs and examples.  Help would be
appreciated! :-)

Cheers,
--Daniel


_______________________________________________
gtkmm-list mailing list
gtkmm-list@...
http://mail.gnome.org/mailman/listinfo/gtkmm-list

[Daniel Elstner]

Am Freitag, den 03.07.2009, 22:48 +0200 schrieb Daniel Elstner:

> > As I see there is no exceptions policy for whole project. Some
> > functions handle exceptions only by returning bool value (example:
> > Glib::file_test ()).and other return both bool and throw exceptions
> > (Glib::KeyFile::load_from_file ()).
>
> That's an API bug, but fortunately mostly harmless.  Just ignore the
> return value, it will always be true when the function actually returns.

Ooops, I just noticed that this is potentially misleading. let me
clarify:

Glib::file_test() doesn't have any exceptional conditions.  The bool
return value is the only result.

When I say it's an API bug, I'm referring to those functions which
appear to do both.

--Daniel


_______________________________________________
gtkmm-list mailing list
gtkmm-list@...
http://mail.gnome.org/mailman/listinfo/gtkmm-list

[José Alburquerque-3]

On Fri, 2009-07-03 at 16:37 -0400, José Alburquerque wrote:

> On Fri, 2009-07-03 at 20:34 +0200, Tomasz Jankowski wrote:
> > Hello!
> >
> > I'm trying to figure out exceptions policy in glibmm/giomm. It's hard
> > to understand which functions exactly throw exceptions. I made some
> > research (I read API and source code), but this issue stays still
> > unclear for me.
>
> Generally, the docs should say if a function throws an exception or not.
> If they don't, the docs need improvement.  Filing a bug (with a patch
> possibly) generally takes care of the lack of clarity.

I really should have mentioned that patches are much appreciated.  As
Daniel said, the documentation isn't perfect but I find them mostly
understandable enough to develop in C++.  If you make an effort to use
the library, you'll probably find that it isn't as hard as it seems even
if it looks like the docs don't have everything you expect them to have.

In the meantime, I filed a patch for the bug you filed.  As a developer
(and not the maintainer) I would encourage you to see if you can
contribute if you find other places in the docs that might be missing
other information that you might think would be good to have.  I hope
it's not asking too much. :-)


--
José Alburquerque

_______________________________________________
gtkmm-list mailing list
gtkmm-list@...
http://mail.gnome.org/mailman/listinfo/gtkmm-list