From: Matthias Clasen Date: Wed, 13 Jun 2007 16:26:59 +0000 (+0000) Subject: Add some docs X-Git-Tag: GLIB_2_13_5~22 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=94327cb6a741dd0ee1cf2abd9fefd495e35b40c8;p=platform%2Fupstream%2Fglib.git Add some docs svn path=/trunk/; revision=5553 --- diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog index 3ec5bf0..363743e 100644 --- a/docs/reference/ChangeLog +++ b/docs/reference/ChangeLog @@ -1,3 +1,9 @@ +2007-06-13 Matthias Clasen + + * glib/tmpl/warnings.sgml: Add some verbiage about + intended use cases for the g_return macros, inspired + by a bugzilla comment by Havoc Pennington. + 2007-06-05 Matthias Clasen * === Released 2.13.4 === diff --git a/docs/reference/glib/tmpl/warnings.sgml b/docs/reference/glib/tmpl/warnings.sgml index 110bc71..66a8d18 100644 --- a/docs/reference/glib/tmpl/warnings.sgml +++ b/docs/reference/glib/tmpl/warnings.sgml @@ -8,6 +8,17 @@ functions to output messages and help debug applications. These functions provide support for outputting messages. + +The g_return family of macros (g_return_if_fail(), +g_return_val_if_fail(), g_return_if_reached(), g_return_val_if_reached()) +should only be used for programming errors, a typical use case is +checking for invalid parameters at the beginning of a public function. +They should not be used if you just mean "if (error) return", they +should only be used if you mean "if (bug in program) return". +The program behavior is generally considered undefined after one of these +checks fails. They are not intended for normal control flow, only to +give a perhaps-helpful warning before giving up. +