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: https://developer.gnome.org/gio/stable/GFile.html#GFile.description And/or in the GIO overview ("Writing GIO applications"): https://developer.gnome.org/gio/stable/ch02.html 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. Philip
Attachment:
signature.asc
Description: This is a digitally signed message part