Re: Documentation inconsistency

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

 



I definitely think the wording can be improved. I'll take a shot at it
later today -- thanks for the report.

On Wed, Aug 5, 2015 at 7:38 AM, Igor Korot <ikorot01@xxxxxxxxx> wrote:
> OK, thx for explanation.
>
> On Wed, Aug 5, 2015 at 9:59 AM, Gergely Polonkai <gergely@xxxxxxxxxxx> wrote:
>> I must agree with Paul here. Try to look at the documentation like this:
>>
>> {The warning. Ignore it for now, but we will come back here soon}
>>
>> The usage. This is how you can and should use the function. It states the
>> behaviour of the function for pre-2.24 and post-2.32 versions. You must
>> consider all if you want to support users with different versions of GLib
>> available.
>>
>> Now get back to the warning part.
>>
>> If you are maintaining legacy code, read it. For you, it means that this
>> function call should be removed from your code on the long run.
>>
>> If you are writing new code, read it. For you, it means that you should not
>> call this function, unless you want to support users with multiple versions
>> of GLib.
>>
>> 2015-08-05 14:19 GMT+02:00 Paul Davis <paul@xxxxxxxxxxxxxxxxxxxxx>:
>>>
>>> On Wed, Aug 5, 2015 at 7:04 AM, Igor Korot <ikorot01@xxxxxxxxx> wrote:
>>>
>>> > Well the trouble is that documentation gives incorrect information:
>>> > First it says function is deprecated and then gives an impression it's
>>> > OK to use it.
>>>
>>> That's the impression you got. It isn't the impression I got.
>>>
>>> The documentation has to cover the following cases:
>>>
>>>    * someone new to GTK/glib, writing new code
>>>    * someone new to GTK/glib, working on existing code that uses
>>> g_thread_init
>>>    * someone with experience using GTK/glib and threads, writing new code
>>>    * someone with experience using GTK/glib and threads, working on
>>> existing code that uses g_thread_init
>>>
>>> I think that the documentation covers all these cases reasonably well,
>>> attempting to
>>> make it clear that you should not use the function anymore, but if you
>>> have existing code that calls it,
>>> you should modify the way the function is called if you choose not to
>>> remove it.
>>>
>>> It could be clearer, yes. But it isn't actually inconsistent.
>>
>>
> _______________________________________________
> gtk-list mailing list
> gtk-list@xxxxxxxxx
> https://mail.gnome.org/mailman/listinfo/gtk-list



-- 
  Jasper
_______________________________________________
gtk-list mailing list
gtk-list@xxxxxxxxx
https://mail.gnome.org/mailman/listinfo/gtk-list



[Index of Archives]     [Touch Screen Library]     [GIMP Users]     [Gnome]     [KDE]     [Yosemite News]     [Steve's Art]

  Powered by Linux