Re: Contribution (updating documentation)

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):

We rewrite that documentation in terms of exceptions for C++. For

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.


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.


[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]