|
2014-02-18 10:21, Murray Cumming skrev:
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+.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 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 |