Re: Discouraging use of sync APIs

On Fri, 2015-02-13 at 11:23 +0100, Sébastien Wilmet wrote:
On Fri, Feb 13, 2015 at 09:33:24AM +0000, Philip Withnall wrote:
 3. Rearranging the docs to promote async functions more
   ? Has not been discussed
   - Big red warnings in the docs may just be ignored by people

Anybody have any thoughts about option #3? I’m wary about filling the
docs up with big red warnings.

Instead of a warning for each sync function, there could be a longer
explanation in the GFile class description:

And/or in the GIO overview ("Writing GIO applications"):

The latter could contain the longer explanation. And the former could
have a reminder with a link to the latter.

Definitely, yet I suspect people generally dive into the docs, search
for the function they want to use, and completely ignore the overview.
We’d need to additionally link to that explanation from each sync
function, which would be a bit rubbish.

Unless we could get gtk-doc to detect (sync, async) function pairs
(either by looking for a corresponding ‘_async’ function or by using a
GIR annotation), then emit a more unobtrusive link back to an overview
of sync-vs-async from each sync function?

We could also use such an annotation to get gtk-doc to automatically add
‘see also’ links between (sync, async) function pairs, and remove all
the boilerplate ‘This is the async version of foo_sync(). There is also
foo_finish().’ text from the docs.

The problem with links back to a sync-vs-async overview is that if
they’re too obvious, experienced developers find them annoying; but if
they’re not obvious enough, inexperienced developers miss them and end
up using sync functions incorrectly.


Attachment: signature.asc
Description: This is a digitally signed message part

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