GNOME Bugzilla – Bug 790510
_baker_begin_cake not defined
Last modified: 2018-05-24 19:53:04 UTC
The examples in the docs for GTask reference _baker_begin_cake and _baker_get_cached_cake, but these are never defined. It's not too difficult to imagine the implementation of _baker_get_cached_data, but the implementation of _baker_begin_cake is not obvious. Code examples should work without requiring the reader to imagine definitions of functions. https://developer.gnome.org/gio/stable/GTask.html
The functions that aren't defined are all "business logic". There's nothing GTask-specific to any of them. Yes, I agree, it's not obvious how you'd write a function to bake a cake, but... (The cake stuff all came from the GSimpleAsyncResult docs originally.) Maybe it just needs some comments explaining the expectations. Eg // _baker_begin_cake() is some external library routine that // asynchronously bakes a cake and then calls the provided callback // routine (baked_cb), passing it the provided user_data (task). See // baked_cb() for the remainder of the GTask integration; Note that // _baker_begin_cake() is assumed to not use GTask in this example.) _baker_begin_cake (self, radius, flavor, cancellable, baked_cb, task); Or alternatively, I guess all the cake stuff could be scrapped and replaced with examples using GFile or i/o streams or sockets.
It took me a minute to realize that _baker_begin_cake was supposed to be some external async function, because (1) it uses the same prefix, so I assumed it was part of the example, and (2) it doesn't use the async/finish convention. If the example is to show how to define one async API in terms of another (a common use case, I think), then I think we ought to just do something realistic on top of an existing async API in GIO. I realize that would be a hefty change that would probably require rewriting all the other examples. As a small change, a comment as you suggest would still help a lot.
-- GitLab Migration Automatic Message -- This bug has been migrated to GNOME's GitLab instance and has been closed from further activity. You can subscribe and participate further through the new bug through this link to our GitLab instance: https://gitlab.gnome.org/GNOME/glib/issues/1301.