* g_return_if_fail:
* @expr: the expression to check
*
- * Verifies that the expression evaluates to %TRUE. If the expression
- * evaluates to %FALSE, a critical message is logged and the current
- * function returns. This can only be used in functions which do not
- * return a value.
+ * Verifies that the expression @expr, usually representing a precondition,
+ * evaluates to %TRUE. If the function returns a value, use
+ * g_return_val_if_fail() instead.
+ *
+ * If @expr evaluates to %FALSE, the current function should be considered to
+ * have undefined behaviour (a programmer error). The only correct solution
+ * to such an error is to change the module that is calling the current
+ * function, so that it avoids this incorrect call.
+ *
+ * To make this undefined behaviour visible, if @expr evaluates to %FALSE,
+ * the result is usually that a critical message is logged and the current
+ * function returns.
*
* If G_DISABLE_CHECKS is defined then the check is not performed. You
* should therefore not depend on any side effects of @expr.
* @val: the value to return from the current function
* if the expression is not true
*
- * Verifies that the expression evaluates to %TRUE. If the expression
- * evaluates to %FALSE, a critical message is logged and @val is
+ * Verifies that the expression @expr, usually representing a precondition,
+ * evaluates to %TRUE. If the function does not return a value, use
+ * g_return_if_fail() instead.
+ *
+ * If @expr evaluates to %FALSE, the current function should be considered to
+ * have undefined behaviour (a programmer error). The only correct solution
+ * to such an error is to change the module that is calling the current
+ * function, so that it avoids this incorrect call.
+ *
+ * To make this undefined behaviour visible, if @expr evaluates to %FALSE,
+ * the result is usually that a critical message is logged and @val is
* returned from the current function.
*
* If G_DISABLE_CHECKS is defined then the check is not performed. You