[glib/deprecated-pragma-docs] docs: Document pitfall of deprecation pragmas

[Emmanuele Bassi <ebassi src gnome org>]

commit 59618d34cf71cc4909a3aa526adacdf9afcbb000
Author: Emmanuele Bassi <ebassi gnome org>
Date:   Thu Dec 13 16:38:38 2018 +0000

    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 f45a1fee8..e98014ce9 100644
--- a/glib/docs.c
+++ b/glib/docs.c
@@ -2207,7 +2207,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:
+ *
+ * |[<!-- language="C" -->
+ *   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
+ *
+ * |[<!-- language="C" -->
+ *
+ *   // 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
+ * ]|
  *
  * Since: 2.32
  */