After an evaluation, GNOME has moved from Bugzilla to GitLab. Learn more about GitLab.
No new issues can be reported in GNOME Bugzilla anymore.
To report an issue in a GNOME project, go to GNOME GitLab.
Do not go to GNOME Gitlab for: Bluefish, Doxygen, GnuCash, GStreamer, java-gnome, LDTP, NetworkManager, Tomboy.
Bug 790510 - _baker_begin_cake not defined
_baker_begin_cake not defined
Status: RESOLVED OBSOLETE
Product: glib
Classification: Platform
Component: docs
unspecified
Other Linux
: Normal normal
: ---
Assigned To: gtkdev
gtkdev
Depends on:
Blocks:
 
 
Reported: 2017-11-17 18:06 UTC by Shaun McCance
Modified: 2018-05-24 19:53 UTC
See Also:
GNOME target: ---
GNOME version: ---



Description Shaun McCance 2017-11-17 18:06:31 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
Comment 1 Dan Winship 2017-11-17 21:38:29 UTC
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.
Comment 2 Shaun McCance 2017-11-18 15:47:15 UTC
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.
Comment 3 GNOME Infrastructure Team 2018-05-24 19:53:04 UTC
-- 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.