hi; On 14 September 2012 14:42, Yehouda Harpaz <yeh@xxxxxxxxxxxxx> wrote: > >> the API reference page on GDK and threads says: >> >> """ > >> [ .. ] > > Several problems with that: > > 1) Not every person reached this page. For example, the developer of > oxygen didn't, and didn't known aboyr gdk_threads_add_timeout until I > told him about it (https://bugs.kde.org/show_bug.cgi?id=306671). There > should be something that points developers to it, becuase this happens > repeatedly. pretty sure we can't do anything about people not reading the documentation. the API reference is the authoritative documentation for GTK+ API, so if you're using GTK+ you need to know about the GTK+ and GDK API reference pages. the API reference is also part of the GTK+ repository, and it's generated and installed when compiling GTK+ - and Linux distributions package it for local consultation. > 2) There are various discussions and commits talking about gdk > threading deperacated, and as you can see from the bug above, people > interpret to mean that they should not use GDK threading functions, > even in GTK 2 and GTK 3. There should be a document that says what you > said, that they need to be used before GTK4, in a place that developers > know that they need to read. that place would still be the API reference. what I said is exactly what was discussed on the mailing lists. > 3) The problem in (2) is made worse by the fact that the new > documentation in 3.6 actually tell people to use g_idle_add. For > example, in this commit: patches and/or bug reports are very much welcome, after asking for clarifications if the documentation is self-contradictory or incomplete. > Instead, this comment should be: > > Deprecated:3.6: see <this page> > > and <this page> is a guidelines page, containing more or less what you > wrote in your first reply. the API reference builder will automatically generate links for the functions, macros, and data types, so you can move within the API reference (or across different API references). if you're just reading the C comments used to generate the documentation then you have access to the whole source code, so you don't really need links. anyway, as I said, feel free to file a bug - a patch attached to it would be stellar; documentation patches are usually reviewed pretty quickly. ciao, Emmanuele. -- W: http://www.emmanuelebassi.name B: http://blogs.gnome.org/ebassi/ _______________________________________________ gtk-list mailing list gtk-list@xxxxxxxxx https://mail.gnome.org/mailman/listinfo/gtk-list
