Add some docs

svn path=/trunk/; revision=5553

diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog
index 3ec5bf0..363743e 100644 (file)
--- a/docs/reference/ChangeLog
+++ b/docs/reference/ChangeLog
@@ -1,3 +1,9 @@
+2007-06-13  Matthias Clasen  <mclasen@redhat.com>
+
+       * 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  <mclasen@redhat.com>
 
        * === Released 2.13.4 ===

diff --git a/docs/reference/glib/tmpl/warnings.sgml b/docs/reference/glib/tmpl/warnings.sgml
index 110bc71..66a8d18 100644 (file)
--- 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.
 <para>
 These functions provide support for outputting messages.
 </para>
+<para>
+The <function>g_return</function> 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. 
+</para>
 
 <!-- ##### SECTION See_Also ##### -->
 <para>