GNOME Bugzilla – Bug 683388
improve documentation for application developers
Last modified: 2014-03-22 16:32:02 UTC
Created attachment 223502 [details] [review] documentation enhancements Dear glib maintainers, I often hangout on the gtk-app-devel mailinglist, and I find that many new glib/gtk programmers struggle with the API reference, especially how to use functions together and how to choose the right function to do something. I would like to add some more examples to the API reference that show how functions can be used. This patch shows a tiny few examples what I would like to add to the API docs. I didn't add many examples yet, I would like to get some feedback if you think these examples are appropriate for the glib and gtk API reference. If you like these kind of examples let me know and I'll try to send some more patches. If you like these examples in a different way, let me know too, and I'll rework this patch.
Review of attachment 223502 [details] [review]: thanks for your patch. ::: glib/glist.c @@ +120,3 @@ + * |[ + * GList *tmplist; + * for (tmplist = g_list_first (list); tmplist; tmplist = g_list_next (tmplist)) { don't use g_list_first() and g_list_next(); we cannot change GList's structure without breaking ABI, so they offer no extra safety while obfuscating the code. also, using a for-loop implies just visiting the list, whereas a operating on the list - e.g. for deleting an element - is better achieved with a while-loop. @@ +208,3 @@ * <note><para> + * The return value is either @list, or the new + * start of the list if @list was NULL. how about merging the original with your change, for instance: """ The return value is either @list, or the new start of the list if @list was %NULL; make sure you store the returned value. """ @@ +212,3 @@ * * <note><para> + * Note that g_list_append() has to traverse to the end of the list the original wording is better. @@ +269,3 @@ * <note><para> * The return value is the new start of the list, which + * will have changed, so make sure you store the new value. 'may' is correct. @@ +542,3 @@ * that it becomes a self-contained list with one element. * + * This function is for example used to move an element in the list. do not split 'is used': """ This function is used, for instance, to move an element in the list: |[ list = g_list_remove_link (list, llink); list = g_list_concat (llink, list); ]| """ though, to be fair, g_list_remove_link() is more commonly used to remove an element from the list before freeing its data, for instance: to avoid re-entrancy in case the free function tries to access the list again. list = g_list_remove_link (list, llink); free_some_data_that_may_access_the_list_again (llink->data); g_list_free (llink);
Emmanuele, thanks for your review. One questions remains: Are more patches to make the API easier to learn for new programmers (with examples) welcome? One remark on your review (whether g_list_prepend 'may' or 'will' return the new start of the list): both seem to be wrong. g_list_prepend returns the newly added list element. If @list is the start of the list, it will thus return the new start of the list. if @list is an element inside the list, it will thus return the newly inserted element inside the list. I'll rework the patch.
Created attachment 224101 [details] [review] the improved patch I reworked the patch with the comments.
ping..
Reopening, as most of the patch didn't get applied.
the patch will need to be reworked to use the MarkDown syntax in place of the DocBook one. the guide to the MarkDown syntax is available on the wiki: https://wiki.gnome.org/Projects/GTK%2B/DocumentationSyntax/Markdown
I think I have to apologize. It seems that all important parts of the patch *have* been committed to git. I checked the on-line documentation (where the changes are not yet visible), but I did not check git (where all changes are already added)... I'm really sorry. You truly do a good job :)