From 50dcccc5040ec0530f03be5dd866a607dcb7df7c Mon Sep 17 00:00:00 2001 From: Emmanuele Bassi Date: Thu, 13 Dec 2018 16:38:38 +0000 Subject: [PATCH] docs: Document pitfall of deprecation pragmas As we discovered in GNOME/gtk#1280, GCC considers the pragmas to control the deprecation warnings as statements. This means we cannot just use the GLib wrappers as markers around the call site, but we must be aware of their side effects. Let's document this, to avoid falling into the trap. --- glib/docs.c | 39 ++++++++++++++++++++++++++++++++++++++- 1 file changed, 38 insertions(+), 1 deletion(-) diff --git a/glib/docs.c b/glib/docs.c index 5d09f433e..f68a1a8b7 100644 --- a/glib/docs.c +++ b/glib/docs.c @@ -2021,7 +2021,44 @@ * has any effect.) * * This macro can be used either inside or outside of a function body, - * but must appear on a line by itself. + * but must appear on a line by itself. Both this macro and the corresponding + * %G_GNUC_END_IGNORE_DEPRECATIONS are considered statements, so they + * should not be used around branching or loop conditions; for instance, + * this use is invalid: + * + * |[ + * G_GNUC_BEGIN_IGNORE_DEPRECATIONS + * if (check == some_deprecated_function ()) + * G_GNUC_END_IGNORE_DEPRECATIONS + * { + * do_something (); + * } + * ]| + * + * and you should move the deprecated section outside the condition + * + * |[ + * + * // Solution A + * some_data_t *res; + * + * G_GNUC_BEGIN_IGNORE_DEPRECATIONS + * res = some_deprecated_function (); + * G_GNUC_END_IGNORE_DEPRECATIONS + * + * if (check == res) + * { + * do_something (); + * } + * + * // Solution B + * G_GNUC_BEGIN_IGNORE_DEPRECATIONS + * if (check == some_deprecated_function ()) + * { + * do_something (); + * } + * G_GNUC_END_IGNORE_DEPRECATIONS + * ]| * * |[