GNOME Bugzilla – Bug 787978
If wrapping a method and ignoring its return value, the documentation still mentions the return value
Last modified: 2017-10-13 15:24:26 UTC
Case in point: Gtk::PrintJob::set_source_file() https://developer.gnome.org/gtkmm/stable/classGtk_1_1PrintJob.html#acbad0bc9a07aee1543bb03f89e8cf108 The method can throw a C++ exception, so the C gboolean return value indicating whether the GError was set is not used, and it should[1] be replaced with a void. But the generated documentation still mentions it: Returns false if an error occurred. This should be improved so that, if a return type is replaced with void, the Returns block does not get written to the documentation. Can that be done? Thanks. [1] https://bugzilla.gnome.org/show_bug.cgi?id=787242#c8
Fixed in the master branch and the glibmm-2-54 branch. When I compared the generated files before and after this fix, I found some methods in glibmm and gtkmm that return void although the corresponding glib/gtk+ functions return gboolean, and there is no GError or exception. I've changed these methods in the master branch. It can't be fixed in other branches. It would break ABI.
Thanks again!
(In reply to Kjell Ahlstedt from comment #1) > When I compared the generated files before and after this fix, I found some > methods in glibmm and gtkmm that return void although the corresponding > glib/gtk+ functions return gboolean, and there is no GError or exception. > I've changed these methods in the master branch. It can't be fixed in other > branches. It would break ABI. Someone on the GTK+ side today told me that changing from a void to a non-void return type doesn't break ABI, but I suspect they're using the very loose, implementation-defined sense of "ABI" that is so typical of all things GObject.
Btw, thanks for going the extra mile and adding a param to _WRAP_METHOD_DOCS_ONLY() for this! I hadn't thought about that case yet. https://git.gnome.org/browse/glibmm/commit/?id=c795521987a50233051b890bb5d8edcb22c74546
> Someone on the GTK+ side today told me that changing from a void to a non-void > return type doesn't break ABI, Really? It might be true when changing from void to bool. A bool value can be returned in a hardware register. I doubt that it's true in general. If the returned value is a large structure, it must be stored on the stack, and I suppose that the caller must know what to do with the stack pointer. > Btw, thanks for going the extra mile and adding a param to > _WRAP_METHOD_DOCS_ONLY() I needed it in gtkmm/gdk/src/events.hg. https://git.gnome.org/browse/gtkmm/commit/?id=02e310149e7ff426ef98181b9e6c3870058e33db
It was phrased generally as "changing a function returning void to return something", but yes, I'm definitely not convinced! Will the gtkmm-3-22 branch get its docs updated with all these great new features? It would be nice to have a fully featured set of docs there. (I've also done a bunch of fixes on the GTK+ side that I hope could filter through eventually.)
The improvements require that the documentation is generated by gmmproc from the glibmm-2-54 branch. gtkmm 3.22 requires only glibmm 2.49.1 or higher. Some improvements (a complete set of flags in signal docs) require regeneration of the *_signals.defs files with a new enough generate_extra_defs.cc. Updates of gtk+ docs will be seen in gtkmm only if the *_docs.xml files are regenerated. I don't know how much of all this will happen.