2014-02-18 10:21, Murray Cumming skrev:
On Tue, 2014-02-18 at 10:08 +0100, Kjell Ahlstedt wrote:
of course the glib/gtk+ documentation does not mention exceptions.
However, it can and should mention the types of errors that it can
produce. The GFile API is pretty good about this, for example, though it
mentions specific error codes rather than generic error types (GIOError
in this case):
https://developer.gnome.org/gio/stable/GFile.html#g-file-read
We rewrite that documentation in terms of exceptions for C++. For
instance:
https://developer.gnome.org/glibmm/stable/classGio_1_1File.html#a3ef959c7ad7096846f26eb8b282e3c68
I think it's worth filing bugs about GTK+ documentation that doesn't do
this, because it's really part of the API. However, C developers can
sometimes find it harder to see that.
Murray
The description of Gio::File::read() and many other method descriptions
with Gio::Error come from gio_docs_override.xml, i.e. they have been
manually converted to suit C++ code. They don't contain @throw doxygen
commands. Some descriptions in glib_docs_override.xml do. I wonder if it
would be possible to automate such conversions. It might be difficult.
It depends on how standardized the descriptions are in glib/gtk+.
Why do we need the docs_override.xml files? I think it's better to put
all manually written or modified documentation in the .hg files. Like so:
1. Let _WRAP_METHOD() or _WRAP_METHOD_DOCS_ONLY() generate the
documentation in a .h file.
2. Copy the documentation from .h to .hg, and make all necessary
modifications.
3. Regenerate the .h file with the modified documentation.
Kjell
_______________________________________________
gtkmm-list mailing list
gtkmm-list@gnome.org
https://mail.gnome.org/mailman/listinfo/gtkmm-list
