Re: Clarification of GTK/GDK locking pre GTK 4.0

[Emmanuele Bassi <ebassi gmail com>]

hi;

On 14 September 2012 14:42, Yehouda Harpaz <yeh lispworks com> 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/