GNOME Bugzilla – Bug 792903
Clarification between g_try_.. functions and their counterparts
Last modified: 2018-01-31 22:11:40 UTC
Created attachment 367426 [details] [review] Proposed patch I just moved the clarification to the beginning of the page. It is more convenient to provide this difference at the beginning. Every time when I see malloc like functions, I think about checking for NULL, but it looks like it is not a case for g_malloc. It works or it fails. It should help to avoid unnecessary NULL check structures in the code. Every g_try_... unction still has the same wording. I may be left there for convenience.
Review of attachment 367426 [details] [review]: ::: glib/gmem.c @@ +74,3 @@ * constructors and destructors). + * + * g_try_... family of functions returns %NULL on failure, contrast to their counterparts: s/contrast/in contrast/ @@ +75,3 @@ + * + * g_try_... family of functions returns %NULL on failure, contrast to their counterparts: + * #g_malloc(), #g_malloc0(), #g_malloc0_n(), #g_realloc(),#g_realloc_n(), which aborts No need for the `#` before the function names. gtk-doc syntax is for functions to be indicated using a trailing `()`. i.e. `g_malloc()` rather than `#g_malloc()`. Missing space after one of the commas. s/aborts/abort/ s/of failure/on failure/ @@ +76,3 @@ + * g_try_... family of functions returns %NULL on failure, contrast to their counterparts: + * #g_malloc(), #g_malloc0(), #g_malloc0_n(), #g_realloc(),#g_realloc_n(), which aborts + * the program of failure. I’d move the paragraph to be just below the previous one, which mentions that the normal memory allocation functions terminate the application on failure. That allows the two paragraphs to be contrasted better.
Created attachment 367502 [details] [review] Rewritten patch Thank you, Philip, for comments and suggestions. I went over once again and I think the new version looks better. Take a look, please.
Review of attachment 367502 [details] [review]: ::: glib/gmem.c @@ +64,3 @@ * These functions provide support for allocating and freeing memory. * + * If call to allocate memory using functions g_new(), g_new0(), g_renew(), s/If call/If any call/ @@ +67,3 @@ + * g_malloc(), g_malloc0(), g_malloc0_n(), g_realloc(), and g_realloc_n() + * fails, the application is terminated. This also means that there is no + * need to check if the call succeeded. On the other hand, g_try_... family s/hand, g_try_.../hand, the g_try_…()/ @@ +78,3 @@ * since these allocators may use different memory pools (and new/delete call * constructors and destructors). + * You introduced a spurious empty line.
Created attachment 367531 [details] [review] One more iteration for the patch OK, should be better. Thanks.
Review of attachment 367531 [details] [review]: Thanks very much.
Pushed to master.